Skip to content
Sign inJoin waitlist

Troubleshooting — Denzel Astro

Most problems with this Astro template come from a typo in a content file, a missing image, a slug that no longer matches, or a setting not rebuilt into the site. 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 (a number where text is expected, an image written as a plain string instead of { "src": …, "alt": … }, 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 of a post’s body 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 nor { "text": …, "ordered": …, "items": [ … ] } (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).

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 (Caught error rendering /blog/…).

The build stops with Home: no post "…". Editor’s Pick and Trending in src/content/pages/home.json name posts by slug (picks.lead, picks.slugs, trending.columns). A slug that no longer exists (a post you deleted or renamed) stops the build: replace it with one that does (Editing the content).

A post is missing from the slider, Recent or the footer. Those lists name posts by slug too, and skip a slug that matches no post: check the spelling in slider.slugs (home.json), sidebar.recent.posts or footer.posts.slugs (site.json).

A card shows a category’s slug instead of its name, and its link is a 404. The post’s category matches no slug in categories.json (the same for author and authors.json). Fix the spelling in the post, or add the category.

A category is missing from Explore Topics or the menu. Both are lists you write: sidebar.topics.categories and navigation in src/content/site.json. Add the new category there.

A category or author page says “No posts in this category yet.” No post names it in its category (or author). “Uncategory” and “Admin” are empty in the demo on purpose.

A photo is cropped in the wrong place. Every photo sits in a frame and is cropped to fill it, from the centre, and a post’s photo appears in many shapes (tall, square, wide). Crop the photo with 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.

A new page’s classes have no effect in npm run dev. The development server adds a new file’s Tailwind classes by itself (src/integrations/rescan.ts); if a style is still missing, save the file once more or restart npm run dev. The build always has them.

/blog works on my laptop but shows “404” on the host. The pages are files (blog.html). Your host needs clean URLs: see Going live.

Vercel doesn’t deploy when I push. The vercel.json of the template turns automatic Git deployments off ("git": { "deploymentEnabled": false }). Remove that entry, keeping "cleanUrls": true (Going live).

The newsletter box says “Something went wrong”. First check the address: the box answers with the error for anything that doesn’t look like name@domain.tld. 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; check that the environment variables are set for the environment you deployed to and that FORM_PROVIDER names a provider that exists. The PUBLIC_ variables are written into the pages when the site builds, so rebuild (or redeploy) after changing any of them (Forms).

The newsletter box says “Thank you!” but nothing arrives. With no PUBLIC_FORM_ENDPOINT and no PUBLIC_FORM_MODE, the form runs in demo mode: it logs the address in the browser console and sends nothing. In server mode, FORM_PROVIDER=console (the default, also when the variable is missing) writes sign-ups only to the server log: set a provider (Forms).

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 search doesn’t find a post. Every word typed must appear in the post’s title, excerpt, category name or author name. The list is built with the site, so a post you just added shows in the search after the next build (or as soon as npm run dev reloads).

The social icons are missing on a phone. On phones the header holds the logo, the search button and the menu button; the social icons are in the phone menu, the sidebar and the footer (Pages and sections).

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 slider doesn’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).

A new post isn’t first on the Blog or in Latest. The lists are sorted by date, newest first: check the post’s date ("2026-11-03", year first). Home’s slider, Editor’s Pick and Trending don’t follow the dates: they show the posts named in home.json.

“Related Posts” or “More Articles by” is missing under a post. No other post has the same category (or author), and the block is left out then.

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;
  • a page: see Pages and sections;
  • a section: delete its line (and its import) from the page file in src/pages/, for example <HomeSlider … /> in src/pages/index.astro; the sidebar: see Pages and sections.

Can I change the fonts to my brand’s? Yes: Making it look like your brand.

Can I add more posts, categories or authors? Yes: copy an entry in its collection and edit it (Editing the content). Add a new category to the menu and Explore Topics too, if it belongs there.

Can a post have several categories or authors? Not as shipped: category and author hold one slug each. Making them lists means changing the schema in src/content/schemas.ts and the functions that read them in src/lib/content.ts and src/lib/to-ui.ts.

Can the Blog show posts page by page? It lists every post on one page. For page-by-page lists, use Astro’s pagination in src/pages/blog.astro.

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 format in src/lib/format.ts ("en-US"), and the interface words “Main” in src/components/site/Header.astro and “Close search” and “Clear” in src/design-system/components/navigation/SearchDialog.astro. 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. Any analytics you add are yours to declare.

Does the site need JavaScript? A little. The pages are static HTML and CSS, and small scripts (no framework) run the phone menu, the search, the slider and the newsletter box. Every word and link is in the HTML, so search engines read the whole site, and visitors without JavaScript see every post on the Blog.

Can I show dates in another format? Yes. The dates (“Sep 14, 2023”) come from formatDate in src/lib/format.ts.

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.

Will it work with Tailwind plugins, React or Vue components, or my component library? Yes. It is a standard Astro + Tailwind CSS 4 project: add packages as usual, and a UI framework with npx astro add react (or vue, svelte) if you want one. 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.