Troubleshooting — Semono 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.
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). The message names the collection, the item and the field, for example
services → business-strategy data does not match collection schema and summary: Required. npm run check finds the
same thing faster.
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 /service/business-strategy).
A photo is cropped in the wrong place. Every photo sits in a frame and is cropped to fill it (from the centre; the team portraits from the top), 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 or changed one of the cards’ icons.
A card’s icon in home.json, about.json or careers.json must be a name of
src/design-system/components/icons/paths.ts. A new icon in 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.
A 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 inquiry could not be delivered (or “New consultation request”, “New job application”); 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).
A 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 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 free consultation” opens cal.com.
The button under the process tabs on Home is the demo’s placeholder: put your own booking page (or /contact) in
process.book.href in src/content/pages/home.json. The button of the same name at the end of a service page is the
form’s submit button (consultationForm.submit in src/content/pages/service.json).
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.
The header is transparent, with white text, all the way down Home.
On Home the header turns light at the section marked headerSwitch, “About Semono”. If you removed it, put
headerSwitch on the section that should take over (Pages and sections).
A page I added starts under the header, or runs under it.
Pages start below a spacer of the header’s height. A page whose first section carries data-header-cover runs under the
header instead, with a transparent header over it (Pages and sections).
The pages don’t slide when I follow a link.
The page change uses the browser’s cross-document view transitions: a browser without them, a visitor who prefers
reduced motion, a click with a modifier key, a link that opens in a new tab and a link to the same page all navigate
normally (Making it look like your brand). Check it on the built site (npm run build, then npm run preview).
To switch it off for everyone, delete the @view-transition rule in src/styles/page-change.css.
The header doesn’t rise when I open a page. That’s on purpose: it rises on the first page of a visit and on a reload, and stays still on the pages reached from another page of the site (Making it look like your brand).
Nothing moves: the ticker, the words, 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 words fade in without rising, and the logo ticker stands still.
A video does not play.
Nothing plays by itself: the card plays its clip when it is pressed (tapped, on a phone), muted and in a loop. If
pressing does nothing, the file can’t be loaded: check src in video (Editing the content):
/videos/intro.mp4 for a file in public/videos/, or a working address, and an MP4 the browser can play. The demo’s
clips come from Pexels’ servers, are not part of the download, and may move: replace them with your own.
Services, Testimonial or Blog show only four (or six) items. That’s on purpose: more appear each time the visitor scrolls close to the spinner under the list (four at a time; the Blog six at a time on desktop). Every item is in the page’s HTML from the start. To change the numbers, see Making it look like your brand.
A new post isn’t first in the Blog.
The Blog 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.
“Related articles” is missing under a post.
No other post has the same category (the spelling and the capital letters must match), and the section is left out
then.
A testimonial shows in the wrong place on Home, or the cards look different from what I expected. The testimonials are read by position: the first is the client story in “Why Choose”, the third the quote on About, the fourth the quote beside the services on Home, and the look of each card of the grid follows its position (Editing the content).
I changed the closing call to action (or the figures) and another page still shows the old one. Each page’s file holds its own copy of the blocks several pages show: change it in each (Pages and sections).
The Contact form offers services I don’t have.
Its “Service Required” list is typed in contactForm.fields.service.options in src/content/pages/contact.json, and
includes two choices that are not services (“Process Optimization”, “Organizational Growth”). Make it match yours.
A legal link in the footer leads to the 404 page.
footer.legalLinks in src/content/site.json are typed addresses: /legal/<slug> must match a slug in
src/content/collections/legal.json.
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, a section or a video? 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<CtaBandSection … />(the photo band with a call to action) insrc/pages/index.astro; - a video: Editing the content.
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 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. Two things are yours to declare: the demo’s video clips, which are fetched from Pexels when pressed (replace them), and any analytics you add. The demo’s Privacy Policy mentions cookies and analytics: edit it to match what your site does.
Does the site need JavaScript? A little. The pages are static HTML and CSS, and small scripts (no framework) play the motion — the blocks and words that rise as you scroll, the header, the ticker — and run the accordions, the process tabs, the video cards, the lists that load more 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, every service and story, and the first posts of the Blog.
Can I show dates in another format?
Yes. Post and legal dates (“May 20, 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.