Troubleshooting and questions
Errors you may hit
Section titled “Errors you may hit”npm install fails, or the site behaves oddly after an update.
Delete node_modules/, .astro/ and package-lock.json, then npm install again. Check node -v is 22.12 or
newer.
Port 4321 is already in use.
npm run dev -- --port 4322, or stop whatever holds the port.
InvalidContentEntryDataError / “… does not match collection schema”.
A collection entry is missing a field, or a field has the wrong type. The message names the collection, the entry and
the field; compare it with src/content/schemas.ts.
Unexpected token or JSON.parse errors.
A JSON file is broken: a missing comma between entries, a comma after the last one, a quote that is not closed, or a
comment (JSON has none). Your editor underlines the spot.
Image /images/… not found: add it to src/assets/images.
The content points at an image that isn’t in src/assets/images/. Check the spelling and the extension — file
names are case-sensitive on the servers that build your site, even when they are not on your laptop.
Remote image not allowed.
An image URL from a CMS or another site: add its domain to image.domains in astro.config.mjs
(Using a headless CMS).
The menu item for the current page isn’t highlighted, or a link 404s — but only on the live site.
Test with npm run build && npm run preview, which behaves like your host. If the preview is right and the host
isn’t, the host is not mapping /about to about.html; see Going live.
A form says “Something went wrong”.
The endpoint rejected the submission or could not be reached. Open the browser’s developer tools → Network, send
again, and read the response of the request to your form service. In server mode, the reason is in your host’s
function logs. After changing a form variable, rebuild — PUBLIC_ values are written into the pages at build time.
The share image or title is the old one.
Facebook, LinkedIn and X cache them. Use their debuggers to refresh, and confirm site.url is your domain.
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 custom cursor / the style guide / a whole page?
Yes. Cursor: delete <Cursor /> from src/layouts/Layout.astro. Style guide: delete src/pages/style-guide.astro.
A page: see Pages and sections.
Can I add React, Vue or Svelte components?
Yes: npx astro add react (or vue, svelte). The template itself uses none, so the pages stay light; add a
framework only where you need one.
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 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.
How do I update to a new version of the template?
Download the new release, copy your src/content/, src/assets/images/, public/ and 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.