Troubleshooting — Compose Digi Astro
Most problems with this Astro template come from a typo in a content file, a missing image, or a setting not rebuilt into the site. Those answers come first.
Then come the questions buyers ask most.
Errors you may hit
Section titled “Errors you may hit”npm install fails, or the site behaves oddly after an update.
Delete node_modules/ and package-lock.json, then npm install again. Check that node -v is 22.12 or newer.
Port 4321 is already in use.
npm run dev -- --port 4322, or stop whatever holds the port.
The build stops with InvalidContentEntryDataError.
A collection item lacks a field that src/content/schemas.ts requires, or a field has the wrong type (a number where
text is expected, a year written as 2023 instead of "2023", one photo in a project’s images where it needs exactly
two, a service without its weekly or monthly plan). The message names the collection, the item and the field, for
example posts → the-role-of-prototyping-in-product-design data does not match collection schema and excerpt: Required.
npm run check finds the same thing faster.
The build stops on a rich-text block.
A block of a rich text (a post’s body, a service’s offer…) has a type other than heading, paragraph or list,
or a list whose items are not lists of blocks (each item is [{ "type": "paragraph", "text": "…" }], in square brackets)
(Editing the content).
The build stops with “key must be a string at line 3 column 25”, or “Unable to load your Astro config”.
A JSON file has a typo: a comma after the last entry of a list, a missing comma or quote, or a comment, which JSON
doesn’t allow. The message gives the line and the column but not always the file, so look in the file you changed last.
When it says it can’t load the config, the file is src/content/site.json (astro.config.mjs reads it).
The terminal shows [file-loader] Error reading data from src/content/collections/….json.
The same kind of typo, in a collection file. Astro can’t read that file, so your changes to it are missing from the
site. Fix the file before you publish.
Image /images/… not found: add it to src/assets/images.
The file must be in src/assets/images/ and the content must refer to it as /images/<file>: same spelling, same
extension. The build also names the page it was rendering (Caught error rendering /projects/…).
A photo is cropped in the wrong place. Every photo sits in a frame and is cropped to fill it, from the centre, and the frames change shape between phone, tablet and desktop. Crop the photo to the shape you want and keep the subject away from the edges (Editing the content).
The build fails but npm run dev was fine.
The build is stricter: it renders every page and processes every image. Read the first error, not the last; it names the
file or the page. Run npm run check too: it checks the types and the content, which the development server doesn’t.
The build stops after I added an icon.
A new icon in src/design-system/components/icons/paths.ts must also be added to icons in
src/components/style-guide/tokens.ts (npm run check reports it), or delete the style guide
(Making it look like your brand).
A new page’s classes have no effect in npm run dev.
The development server adds a new file’s Tailwind classes by itself (src/integrations/rescan.ts); if a style is still
missing, save the file once more or restart npm run dev. The build always has them.
Scripts fail with 504 (Outdated Optimize Dep) in the browser console and nothing moves.
The development server kept old copies of the packages after a restart (often after editing astro.config.mjs). Stop
it, delete node_modules/.vite, and start npm run dev again.
/about works on my laptop but shows “404” on the host.
The pages are files (about.html). Your host needs clean URLs: see Going live.
The form says “Something went wrong”.
Static mode: the endpoint answered with an error; open the browser’s console for the reason, and check
PUBLIC_FORM_ENDPOINT. Server mode: the reason is in your host’s function logs, after [forms] New contact request could not be delivered (your notification title); check that the environment variables are set for the environment you
deployed to and that FORM_PROVIDER names a provider that exists. The PUBLIC_ variables are written into the pages when
the site builds, so rebuild (or redeploy) after changing any of them (Forms).
The form says “Thank you” but nothing arrives.
With no PUBLIC_FORM_ENDPOINT and no PUBLIC_FORM_MODE, the form runs in demo mode: it logs the fields in the browser
console and sends nothing. In server mode, FORM_PROVIDER=console (the default, also when the variable is missing)
writes submissions only to the server log: set a provider (Forms). If you added a field named fax,
rename it: that name is the hidden spam trap, and a submission that fills it is dropped.
The form won’t send and a field turns red. The first name, the last name and the e-mail are required, and the e-mail must look like an address (“Please enter a valid email address.”). The other fields can be empty unless you made them required.
The build stops with NoAdapterInstalled.
PUBLIC_FORM_MODE=server adds a route that runs on a server, which needs your host’s adapter: npx astro add vercel
(or netlify, node, cloudflare). To stay fully static, leave PUBLIC_FORM_MODE empty (Forms).
A service is missing from the form, or an old one is still there.
The checkboxes are the names of src/content/collections/services.json, in its order: edit the services and rebuild.
The About video plays the template’s film, or doesn’t play.
The video is the YouTube video whose id is video.youtubeId in src/content/pages/about.json: put your own
(Editing the content). A video whose owner turned off embedding, a private video or no connection leaves
the window empty; an unlisted video works.
A project page lists fewer services than I wrote.
A project’s services are service slugs ("email-marketing"), not names. A slug with no matching service in
services.json is left out.
“Other Services” or “More Projects” shows fewer cards.
They show the first four other services and the first three other projects: with fewer items in the collection, there is
less to show. Home’s list of projects also starts at the fourth project (projects.listOffset in home.json).
The phone menu cuts off my new link.
It opens to a fixed height that fits five links: raise 386px in src/components/site/header.ts by 38 px per extra
link (Pages and sections).
The footer’s big line runs off the screen.
It is scaled to fill the width for the demo’s “Tell Us Your New Ideas”: lower the 8.532cqw in
src/components/site/Footer.astro for a longer line (Making it look like your brand).
The share image or title is the old one.
Facebook, LinkedIn and X cache them. Use their debuggers to refresh, and confirm that site.url is your domain.
Nothing moves: the tickers, the project photos. The visitor’s system (yours, if you see it) has “reduce motion” switched on, and the site honours it (Making it look like your brand). The tickers and the scroll effects stand still; fades and colour changes stay.
Projects or Blog shows only a few items.
That’s on purpose: five on desktops, four on tablets and three on phones, then as many more with each press of “Load
More” (Careers shows four at a time). Every item is in the page’s HTML from the start. To change the numbers, set
list.pageSizes in src/content/pages/projects.json or blog.json, or careers.pageSizes in careers.json.
A new post isn’t first on Blog or Home.
The site doesn’t sort by date: it shows the posts in the order of src/content/collections/posts.json, newest first in
the demo. Put the new post at the top of the list.
I changed my e-mail (or the social links, or the booking link) and another place still shows the old one.
Some details have a copy in more than one file: the e-mail in site.json and the job openings, the social links in
site.json, the page headers and the team, the booking link in home.json and the footer
(Editing the content).
Questions
Section titled “Questions”Can I use this template for a client? See License: that is the one place that answers it for your licence.
Can I remove the style guide, a whole page or a section? Yes:
- the style guide: delete
src/pages/style-guide.astro,src/components/style-guide/andsrc/design-system/scripts/style-guide.ts; - a page: see Pages and sections (Careers with its job openings, for example);
- a section: delete its line (and its import) from the page file in
src/pages/, for example<QuoteSection … />insrc/pages/index.astro, or<TestimonialSection … />insrc/pages/services.astro.
Can I hide the prices?
Yes: the plan card is part of src/components/sections/ServiceDetailsSection.astro (<PricingCard … />); delete that line
(and its import), and “Key Benefits” takes the full width. The plan texts in service.json (plans) are then unused.
Can I change the fonts to my brand’s? Yes: Making it look like your brand.
Can I turn off the custom cursor? Yes: Making it look like your brand.
Do I need a CMS? No. Content is files you edit. Add one when somebody who does not use a code editor has to publish (Using a headless CMS).
Can visitors book a call or pay online?
“Book a call” links to a scheduling page (https://cal.com/ in the demo): put the address of your own Cal.com, Calendly
or other booking page in hero.links (home.json) and the footer’s Support column. The plans’ “Book an intro call” goes
to the contact form; payments need a service of your own (Stripe Payment Links, for example) linked from the buttons.
Can I write the site in another language?
All the copy is content, so write it in your language. Then set lang and og:locale in src/layouts/Layout.astro,
the date format in src/lib/format.ts ("en-US"), and the menu’s name for screen readers, “Main”, in
src/components/site/Header.astro. The template has no language switch or language-based routing.
Does the site need a cookie banner?
As shipped, the template sets no cookies and loads no third-party scripts: the fonts are served from your own domain.
The About video loads YouTube’s player (from youtube.com) only when a visitor presses Play. Any analytics you add are
yours to declare.
Does the site need JavaScript? A little. The pages are static HTML and CSS, and small scripts (no framework) play the motion — the scroll effects, the cursor, the hovers — and run the phone menu, the service rows, the plan switch, the testimonial slider, the process chart, the video window, Load More and the form; the tickers are CSS. Every word and link is in the HTML, so search engines read the whole site. Visitors without JavaScript see every block in place; the items behind “Load More” stay hidden, the service rows stay as they are on load and the switch does nothing.
Can I show dates in another format?
Yes. The dates (“Jun 25, 2024”) come from formatDate in src/lib/format.ts.
Can I sell a site I build with this? Building sites for clients is what the licence is for; reselling the template itself as a template is not. The licence has the exact wording.
Will it work with Tailwind plugins, React or Vue components, or my component library?
Yes. It is a standard Astro + Tailwind CSS 4 project: add packages as usual, and a UI framework with
npx astro add react (or vue, svelte) if you want one. The design tokens are plain CSS variables, so other
libraries can read them.
How do I update to a new version of the template?
Download the new release and copy your src/content/, src/assets/images/, public/ and your theme.css into it.
Then re-apply any component changes you made. CHANGELOG.md lists what moved.
Can you customise it for me, or build my site? Yes. Marcframe, the studio behind this template, updates templates to your needs (brand, content, new pages and features), builds custom templates and designs new websites. Get in touch at marcframe.com/contact or hire us on Contra.
Something is broken and none of this helps. Support and updates: https://framebrick.co/support. Send the page, the browser, and the error text or a screenshot: it makes the answer much faster.