Troubleshooting — Goeboek Astro
Most problems with this Astro template come from a JSON typo, a missing image, a slug that no longer matches or a form setting not given to 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 (an image written
as a plain string instead of { "src": …, "alt": … }, a price or size written in quotes, a for other than rent
or sell, a rich-text description 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: wider than tall on the property cards and pages, taller than wide on the post cards. Keep the subject in the middle (Editing the content).
A card shows “No Name”, “No Location” or “Uncategory”.
The property’s agent, location or category doesn’t match the slug of an item in agents.json, locations.json
or categories.json. Check the spelling: slugs are lower case with hyphens (staten-island).
A new property doesn’t show on Home.
Home’s slideshow shows the first four properties of properties.json and Featured the next six. Move the new one up
the file (Editing the content).
“Related properties” or “More in …” is empty on a property page.
No other property has the same category and type (for), or the same location. The Related block keeps its title and
“More Property”, as in the original design (the demo’s Marble House shows none).
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” (or opens its thank-you page) 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”. 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 required field is empty or 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.
Addresses end in .html, or /property/… shows a 404 on my host.
Pages are built as files (property/marble-house.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 video or the map is blank.
A property’s video must be a YouTube link (https://www.youtube.com/watch?v=… or https://youtu.be/…); without
one the Video block is left out. The Contact map searches Google Maps for map.query in contact.json: write an
address Google can find. Both need the visitor to be online and not blocking those services.
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 slideshows don’t move. The visitor’s system (yours, if you see it) has “reduce motion” switched on, and the site honours it: the slides change only with the arrows and dots (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).
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, the blog or the Add property page? Yes:
- the style guide: delete
src/pages/style-guide.astro; - the blog: delete
src/pages/blog.astroandsrc/pages/blog/,<LatestPosts … />on Home, the links to/bloginsite.jsonand the posts insrc/pages/sitemap.xml.ts; - Add property: delete
src/pages/add-property.astroandsuccess-add-property.astro, the header’s “Add Property” inheaderActionsand their lines in the sitemap (Pages and sections).
Can the filter combine choices (a location and a price range)? Not built in: the filter is a list of links to the listing pages, one choice at a time, as in the original design, so every listing is a real page that search engines find. A combined filter needs a script that hides the cards that don’t match, or a search service.
Can I mark which properties are featured?
Home takes them by position: the first four in the slideshow, the next six in Featured. Order properties.json (or your
CMS) accordingly, or add a featured field to the schema and filter by it in src/pages/index.astro.
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 property pages do: image="/images/share.jpg" imageAlt="…".
Can I change the currency or the units?
The price is a number shown with a dollar sign by formatPrice in src/lib/format.ts; change it there. The size unit
(“m2”) is propertyCard.sizeUnit in sections.json and sizeUnit / heightUnit in property.json.
Can I add a dark theme?
The design is light only. The colours are tokens (Making it look like your brand), so you can change them, but the
translucent blacks are written on the components (bg-ink/3, border-ink/5) 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 listings (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 and number formats in src/lib/format.ts ("en-US"), and the interface words listed in
Editing the content. The template has no language switch or language-based routing.
Does the site need a cookie banner? The template sets no cookies of its own and serves its fonts from your own domain. The property pages embed YouTube and the Contact page embeds Google Maps, and those services can set cookies; a form service you choose, and anything you add (analytics), is yours to declare too. Check what your visitors’ country requires.
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.