Troubleshooting — Fitbricks Astro
Most problems with this Astro template come from a content typo, a missing image or a form variable not set on the host. 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 (text where a
number is expected, as a program’s duration or a plan’s price; a level that isn’t "easy", "medium" or
"hard"). The message names the collection, the item and the field. 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. The same error with Image not found (no file name) means a
program names a category that doesn’t exist: check its category.
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 (a program photo is a card and a tall cover). Keep the subject in the middle (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.
/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”.
In static mode, the service refused the request: check PUBLIC_FORM_ENDPOINT (and PUBLIC_FORM_ACCESS_KEY for
Web3Forms), that the form exists at the service and accepts your domain, and that you rebuilt after changing the variable.
In server mode the reason is in your host’s function logs, after [forms] Get in Touch could not be delivered (or “Claim
Free Trial”, “Book Your Class Now”): a missing variable, or a FORM_PROVIDER that doesn’t exist. Mailchimp also refuses
addresses it considers fake or that unsubscribed before.
A form says “Thank you” but nothing arrives.
Without PUBLIC_FORM_ENDPOINT and without server mode the forms run in demo mode: nothing is sent, and the fields go
to the browser console. In server mode with FORM_PROVIDER=console (the default) they go only to the server log. Set a
destination (Forms). If you added a field named fax, rename it: that name is the hidden spam trap.
A form won’t send and points at “Email” or “Contact Time Preferences”.
The e-mail is required on every form, and the contact time on the contact and free-trial forms (as in the original
design; “Anytime” is its prompt, not a choice: pick a time of day). To make one optional, set its required to false (Forms).
A new program, club or post doesn’t show on Home.
Home shows the first six clubs, programs and posts of their files (Editing the content).
Move the item up in its file. Posts are sorted by date, newest first: check the new post’s date ("2025-08-18").
The build stops after adding or editing a program.
Its category names no entry of program-categories.json: correct the slug or add the category.
A club page lacks a facility or a class.
A club shows the facilities and programs whose slugs are in its facilities and programs; a slug that matches no item
is skipped. Check the spelling against facilities.json and programs.json.
The Default category’s page is empty. As in the original design: no program belongs to it, and it is not in the filters. Give it programs, or delete it (Editing the content).
Programs, Clubs or Trainers show only the first few items.
They load more each time the end of the list comes into view; scroll down. Visitors without JavaScript see them all.
Change the step in list.pageSize of the page’s copy.
A program’s video shows nothing.
video must be a YouTube link (https://www.youtube.com/watch?v=…, youtu.be/… or an embed link); anything else
leaves the space empty.
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 quotes in Home’s hero don’t slide. The visitor’s system (yours, if you see it) has “reduce motion” switched on, and the site honours it: the quotes still change, without the movement (Making it look like your brand).
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.
Are the legal pages ready to use?
No. The Privacy Policy and the Terms & Conditions are samples written for the demo gym, with a placeholder
[Your Country/State]. Have them written for your business and checked for your country before you publish
(Editing the content).
Can I keep the program videos?
No. They are YouTube videos by other creators, embedded as examples of the layout. Replace each program’s video with
your own before launch.
Who is Waras? The made-up gym of the demo: its logo, name, e-mails, phones and addresses are placeholders. Replace them with your own (Editing the content).
Can I remove the style guide, a whole page or a section? Yes:
- the style guide: delete
src/pages/style-guide.astro; - a page: see Pages and sections;
- a section: delete its line in the page file, for example
<CoachingSection … />insrc/pages/index.astro; the CTA and trainers bands are switched off in the page’s copy.
I don’t have an app. Can I remove the app sections?
Yes: delete <AppSection … /> in src/pages/index.astro, the “All-in-One” cards in home.json (membership.features) and
about.json (why.items), and the badges in src/components/site/Footer.astro.
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 members book or pay online? Not by themselves: the booking and free-trial forms send a request to you (Forms). The plans on the program pages are information with a “Start Your Free Trial” button. For bookings or payments, link the buttons to your booking system, or connect one.
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 and the date format in src/lib/format.ts ("en-US"). The template has no
language switch or language-based routing.
Does the site need a cookie banner? As shipped, the template sets no cookies of its own and the font is served from your own domain. The program pages show the YouTube thumbnail from YouTube’s image server, and the player loads from youtube-nocookie.com only when the visitor clicks play. A form service you choose receives what visitors type: name it in your Privacy Policy. Any analytics or embeds you add are yours to declare.
Can I show dates in another format?
Yes. Post and legal dates (“Aug 18, 2025”) come from formatDate in src/lib/format.ts.
Will it work with Tailwind plugins, shadcn/ui, or my component library?
Yes. It is a standard Astro + Tailwind CSS 4 project: add packages as usual, and framework components (React, Vue,
Svelte) through npx astro add react. 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.