Skip to content
Sign inJoin waitlist

Troubleshooting — Cerette Astro

Most problems with this Astro template come from a content file with a typo, a missing image, or a setting that was not rebuilt into the site. Those answers come first.

Then come the questions buyers ask most.

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 plain string where an image needs src and alt). The message names the collection, the item and the field. npm run check finds the same thing faster.

The build stops on a project’s images. A project has exactly four images, no more and no fewer (Editing the content).

The build stops on a post’s category. A post’s category must be one of Architecture, Construction and Interior, spelled the same. To add one, add it to the list in postSchema in src/content/schemas.ts (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.

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).

/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 Home video doesn’t play. Check hero.video.src in src/content/pages/home.json: a file in public/ is written from the site’s root (/videos/hero.mp4 for public/videos/hero.mp4). Browsers play muted MP4 (H.264) files everywhere; until the video plays, the poster shows. The demo’s video is hosted on another site and may stop working: use your own (Editing the content).

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] <your notification title> could not be delivered; check that the environment variables are set for the environment you deployed to and that FORM_PROVIDER names a provider that exists. With Mailchimp, a form sent without an e-mail fails too. 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 forms run in demo mode: they log the fields in the browser console and send 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: the browser asks to fill in Project type or Project budget. Both lists are required and start on their placeholder: the visitor must pick a choice. To make them optional, remove "required": true from them in src/content/pages/forms.json (Forms).

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).

“Book a call” opens cal.com. That is the demo’s placeholder: put your own booking page (or /contact) in the buttons of home.json, about.json, projects.json, services.json and cta.json (Editing the content). The bookingHref in site.json isn’t used by any page.

I changed the e-mail in site.json and Contact still shows the old one. The Contact page has its own copy of the e-mail, phone and address, in src/content/pages/contact.json. Change both.

The header is white text on a light photo. Over Home’s video, a project’s cover and the 404 photo, the header is transparent and drawn in white. The photos have a dark veil (bg-ink/50) in src/components/sections/HomeHero.astro, ProjectHero.astro and NotFoundSection.astro: strengthen it, or choose a darker photo.

Nothing moves: the hero text, the titles, the blocks. 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). Blocks and text fade in without moving.

Blog shows only some posts. That’s on purpose: a page more appears each time the visitor scrolls close to the spinner under the grid. Every post is in the page’s HTML from the start. To change the number, set blogPage.pageSize in src/content/pages/blog.json. About’s team works the same way on tablets and phones (team.pageSize in about.json).

A new post isn’t first. Posts are sorted by their date, newest first, not by their place in the file. Check its date ("2026-06-01").

“Similar posts” shows nothing, or fewer than three. It lists the other posts of the same category, up to three. With none, the heading and its button stay and the row is empty: write more posts in that category, or remove the section from src/pages/blog/[slug].astro.

A project’s service is missing from its Services. Its services must hold the slugs of services in services.json, spelled the same (architecture, not “Architecture”); a slug that matches nothing is left out.

I changed the figures, the quote or “Why Cerette” and another page still shows the old ones. Home, About and Services each hold their own copy (Pages and sections).

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.

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 and src/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 <HomeTestimonials … /> in src/pages/index.astro (Pages and sections).

Can I use a photo instead of the Home video? Yes: the poster already shows until the video plays. Replace the <video> in src/components/sections/HomeHero.astro with <FillImage src={content.video.poster} alt="" sizes="100vw" priority /> (from src/design-system/components/media/FillImage.astro), and keep the veil over 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 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 formats in src/lib/format.ts ("en-US") and the few interface words listed in Editing the content. 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 demo’s Home video is loaded from another site; once you host your own, nothing is. 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 hero text, the titles, the blocks rising, the hovers — and run the header, the phone menu, the services switcher, the team picker, the loading of the Blog and the team, and the forms. Every word and link is in the HTML, so search engines read the whole site. Visitors without JavaScript see every block in place and the first page of the Blog.

Can I show dates in another format? Yes. The dates come from formatDate (cards and posts) and formatLongDate (legal pages) 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.