Skip to content
Sign inJoin waitlist

Troubleshooting — Brickfolio Astro

Most problems with this Astro template come from a JSON typo, a missing image, an anchor that no longer matches or a form setting not given to the host. 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 (an image written as a plain string instead of { "src": …, "alt": … }, a gallery image without visible, a rich-text body that is not a list). The message names the collection, the item and the field. npm run check finds the same thing faster.

The build stops on a rich-text block. A block has a type other than heading, paragraph or list, a heading level outside 2 to 6, or a list item that is neither a string, { "text", "ordered", "items" } nor { "text", "blocks" } (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).

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: 3 : 2 on a project or post page, a fixed height on the cards. Keep the subject in the middle (Editing the content).

A header link doesn’t scroll to its section. The link’s href in navigation (src/content/site.json) must match the section’s id in src/content/pages/home.json: #project goes to the section whose id is project.

The profile card stops sticking before the end of Home. You added or removed a block of Home’s column: change lg:row-span-11 on <Profile> in src/pages/index.astro to the number of blocks beside it (Pages and sections).

A new page or class has no styles in npm run dev. Save the file once more; the development server picks up the classes of a new file on its next change (src/integrations/rescan.ts). npm run build always sees every file.

The build stops with NoAdapterInstalled. PUBLIC_FORM_MODE=server needs an adapter for your host: npx astro add vercel (or netlify, node, …), or empty the variable to stay static (Forms).

A form says “Thank you” but nothing arrives. The forms are in demo mode: PUBLIC_FORM_ENDPOINT is empty (or was set after the build). Set it, restart npm run dev, and rebuild the site on your host: the value is written into the pages when they are built (Forms). In server mode with FORM_PROVIDER=console, submissions only reach the server log.

A form says “Something went wrong”. A field is missing or isn’t an e-mail address, the service answered with an error (a wrong endpoint, a form not yet confirmed at Formspree, a missing Web3Forms key), or, in server mode, a provider variable is missing (the reason is in your host’s function logs). Check the endpoint in a browser tab, and redeploy after changing variables.

“More Posts” is missing under a post. No other post has exactly the same category; the block and its line are left out then. Check the spelling.

Home shows only four projects or four posts. That’s pageSize in src/content/pages/home.json; “More Projects” and “More Posts” show the rest, four at a time.

A new post isn’t first. Posts are sorted by date, newest first: check the post’s date ("2026-11-02", year, month, day). Projects keep the order of projects.json: put a new one at the top to show it first.

Addresses end in .html, or /project/… shows a 404 on my host. Pages are built as files (project/ecoshop-….html). Vercel serves them at clean addresses with the included vercel.json; Netlify and Cloudflare Pages do it by default; on Apache or nginx add the rule in Going live.

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 tickers or the roles don’t move. 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).

Vercel doesn’t deploy when I push. vercel.json holds "git": { "deploymentEnabled": false }, which turns automatic deployments off: delete that entry and keep "cleanUrls": true (Going live).

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 section or the blog? Yes:

  • the style guide: delete src/pages/style-guide.astro;
  • a section: delete its line in src/pages/index.astro (Pages and sections);
  • the blog: delete <Blog … />, its link in navigation, src/pages/blog/ and the posts in src/pages/sitemap.xml.ts.

Can I have a page that lists every project or every post? Not built in: Home lists them four at a time. Add a page (Pages and sections) that maps getProjects() to ProjectCards, as src/components/sections/Projects.astro does.

Can Home have a share image? Yes. The original design has none, so Home shares its title and description only. Put an image in src/assets/images/ and pass it to Layout in src/pages/index.astro, as the project pages do: image={imageUrl("/images/share.png")} imageAlt="…" (imageUrl from src/design-system/utils/image.ts).

Can I add a light theme? The design is dark only. The colours are tokens (Making it look like your brand), so you can change them, but the translucent whites are written on the components (text-white/80, bg-white/10) and would need a second set.

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 interface words (“Main”, “out of 5”) 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. A form service you choose, and anything you add (analytics, embedded videos), is yours to declare.

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.

Can I add React, Vue or Svelte components? Yes. It is a standard Astro project: npx astro add react and use them as islands. The template itself needs none; its interactive parts are small scripts in src/design-system/scripts/.

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.