Troubleshooting — Metuo 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, one small photo in images where a service needs exactly two, two alt texts in imageAlts where it
needs three). The message names the collection, the item and the field, for example
posts → how-self-awareness-shapes-daily-growth 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 post’s or legal page’s body 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 /blog/…). Videos are the exception:
they go in public/ (Editing the content).
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.
/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 session 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 the e-mail field turns red. The e-mail is required and 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 session type 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 videos don’t play, or play someone else’s clip.
In the demo they play from the Pexels website; with no connection, or if Pexels moves the file, the band stays empty.
Put your own clips in public/ and their paths in video.src (Editing the content).
The header stays transparent over the page (white links on a light background).
On a page that starts with a photo title, the header turns solid when a section marked headerSwitch reaches the middle of
the screen. If you removed or replaced that section, give the next one headerSwitch on its Section
(Pages and sections).
The header hides the top of my new page.
The header is fixed. A page that starts with a photo title runs under it on purpose; any other page gets a spacer of the
header’s height by itself. If your first section carries data-header-cover without a photo behind the header, remove it.
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 hero’s words, the zoom, the parallax. 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 words fade in without rising and the scroll effects stand still; the videos still play.
The Journal shows only six posts.
That’s on purpose: six more appear each time the visitor scrolls near the end of the list. Every post is in the page’s
HTML from the start. To change the number, set list.pageSize in src/content/pages/blog.json.
A new post isn’t first on the Journal 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.
“More insights for you.” is missing under a post.
No other post has the same category (spelled exactly the same), and the section is left out then.
I changed the numbers (or the social links, or my e-mail) and another place still shows the old one.
Some details have a copy in more than one file: the numbers in home.json and service.json, the social links in
site.json and shared.json, the e-mail in site.json, shared.json and faq.json
(Pages and sections).
The legal pages say “[Your Company Name]”.
They are samples: write your own texts in src/content/collections/legal.json (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.astroandsrc/components/style-guide/; - a page: see Pages and sections;
- a section: delete its line (and its import) from the page file in
src/pages/, for example<PricingSection … />(the plans) insrc/pages/index.astro, or<VideoSection … />on Home or About.
Can I hide the prices?
Yes: delete <PricingSection … /> from src/pages/index.astro and src/pages/service.astro. The “Get started” buttons
go with it.
Can I change the fonts to my brand’s? 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 I take online bookings or payments?
The booking form sends a request; you confirm the session yourself. To let clients pick a time and pay, link your
scheduling tool (Cal.com, Calendly, Acuity…) from the “Book a session” button (bookLink.href in site.json) and the
other buttons that point at /contact, or embed its widget on a page of your own.
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 two interface words, “Main” and “Menu”, 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 font is served from your own domain. The demo videos come from the Pexels website until you replace them. 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 parallax, the scroll zooms, the pinned stories, the points lighting up, the hovers — and run the header, the phone menu, the rows that open, the plans’ switch, the team bios, the Journal’s loading and the form. Every word and link is in the HTML, so search engines read the whole site. Visitors without JavaScript see every block in place and every post on the Journal; the rows stay as they are on load and the switch does nothing.
Can I show dates in another format?
Yes. The dates (“May 28, 2026”) 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.