Troubleshooting — Ciketo Astro

Most problems come from a content file with a typo, a missing image, or a setting that was not rebuilt into the site. The answers below cover those first, then the questions buyers ask most.

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 → ocean-freight 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 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. The build doesn’t stop, but it 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 /services/road-freight).

A lane is missing from a service page. The service lists its lanes by slug in lanes.items; each one must be exactly the slug of a lane in lanes.json ("jebel-ali-rotterdam"). A slug that matches no lane is skipped without an error.

“Other Posts” is missing at the end of a post. It lists the other posts with the same category, spelled the same way. A post that is alone in its category has none, and the section is left out.

A link in the footer leads to “404” after renaming or removing a service. The footer’s Services column is a fixed list (footer.services.links in src/content/site.json): update the link there. The same goes for the legal links (footer.legal).

/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.

The quote 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; the route also answers with an error when the name, the e-mail or the shipping method is empty. Environment variables are read when the site builds, so rebuild after changing them.

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).

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 white on a page where it should be dark, or the other way round. The header is transparent with a white logo, clock and button at the top of Home, Contact and 404, which open with a dark photo. Those pages pass cover to Layout, and their first section carries data-header-cover (Making it look like your brand); add or remove both together.

The header clock is empty. A small script writes the visitor’s time and date when the page loads; until then, or with JavaScript switched off, the clock stays hidden, so the time of the build never shows.

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

• the style guide: delete src/pages/style-guide.astro and src/components/style-guide/;
• a page: see Pages and sections;
• a section: delete its line (and its import) from the page file in src/pages/;
• the header clock: delete the two <Clock … /> lines (and the import) in src/components/site/Header.astro.

Can the header clock show our office’s time instead of the visitor’s? Yes: in src/design-system/scripts/clock.ts, add your time zone to both Intl.DateTimeFormat options, for example { hour: "2-digit", minute: "2-digit", hourCycle: "h23", timeZone: "Europe/Amsterdam" }. The language of the date is clock.locale in src/content/site.json.

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 the blog show all posts at once? Yes: give <BlogListSection> in src/pages/blog.astro a larger pageSize, for example pageSize={24}; with no more posts than that, the spinner doesn’t show.

Does the site need JavaScript? The pages are plain HTML and CSS. Small scripts add the motion, the phone menu, the clock, the services list, the steps, the testimonials, the FAQ, the logo row, the blog’s next posts and the form; no framework runs in the browser.

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 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.