Troubleshooting

Find your symptom below. If none matches, copy the full error from the terminal into your AI assistant with: “Explain this error in one sentence, then fix it with the smallest change.”

My Change Doesn’t Show Up

Is the dev server running? The terminal should show npm run dev without errors.
Did you edit the right file? A page block overrides the section file. Search the project for the old text to find where it really comes from: see Find Where Any Text Comes From.
Is the key spelled right? Misspelled keys are ignored without an error. Compare with the comments in the file.
Is the page block named right? A block with a wrong name, for example faq: instead of faqSection:, is ignored without an error. Copy the name from the comments in the page file or from Sections.
Is the key in the right place? layout sits at the top level of a section block (heroSection: layout: "split"), not under options:. A key in the wrong place is ignored.
Did you edit the other language? /fr/ pages read the french/ files.
Did you change config.toml multilingual settings or trailingSlash? Restart npm run dev.
Hard-refresh the browser: Ctrl + Shift + R (⌘ + Shift + R on Mac).

A Section Or Page Disappeared

Check enable in the section file and in the page’s block.
Check draft in the page or entry. Drafts show in npm run dev but not on the built site.
Check that the section’s line is still in the route file in src/pages/[...lang]/.
For list pages, check draft in the collection’s -index.md.

Header items need "enable": true. An item without it is hidden. See Menus.

The Site Shows An Error After I Edited A File

YAML (frontmatter): check indentation (2 spaces, no tabs), quotes around text with : or #, and that list items start with - .
JSON (menus, i18n): check for a missing or extra comma, usually at the end of the item you edited.
“expected boolean, received string”: write true, not "true".
“expected number”: write 4, not "4".
An error that names a section field, such as layout or color with a list of allowed values: the value in the section file or page block is not one of them. Copy one from the comment next to the field.
An .mdx file fails on a line with {, }, or <: put that text in backticks.

Markdown, YAML, TOML & JSON explains each format.

An Image Doesn’t Appear

Frontmatter images (image: and similar fields): the file should be in src/assets/images/ (public/images/ also works) and the path must start with /images/.
Images in Markdown text (![...](...)): the file must be in public/, for example public/images/gallery/1.jpg for /images/gallery/1.jpg.
Check the exact file name, including upper and lower case and the extension (.jpg vs .jpeg).

Search Says It Works On The Built Site

That’s normal in npm run dev: there is no search index yet. Search works after npm run build: test it with npm run preview.

Forms Show A Warning

The warning appears in npm run dev until the form has a real endpoint. Set contactFormAction and [settings.subscription] formAction in config.toml, or form.action in the auth files (the contact and demo forms also accept their own form.action in their section files). See Forms.

The Contact Form Doesn’t Deliver

Formsubmit: confirm the activation email it sends after the first message.
Netlify: form detection must be on in the Netlify dashboard, and contactFormProvider = "netlify".
Test from the live site, not from localhost.

`npm run dev`Never Starts (Windows)

If the terminal stops at [toml-watcher] Watching config.toml for changes..., run the two parts in two terminals: npm run toml:watch -- --watch and npx astro dev. See Installation.

`npm ci`Or`npm install`Fails

Check node -v: it must be 22.12.0 or later.
Delete the node_modules folder and run npm ci again.
Use npm, not Yarn or pnpm: the theme ships a package-lock.json.

Build Fails With A Rename Or Cache Error

Don’t run astro-check, build, and dev at the same time in the same folder; they share a cache. Stop everything, then run one command at a time. If it keeps failing, delete the .astro folder and try again.

The Build Warns About The Site URL

A yellow [site] The site URL is still a placeholder line in the npm run build output (just before the page(s) built line) means [site] baseUrl is still https://example.com. Set it to your real address in config.toml, or set a SITE_URL environment variable for the build. See SEO & AI Visibility.

The Live Site Has Wrong Links Or Previews

Set [site] baseUrl in config.toml to your real address and deploy again. If your host sets a SITE_URL environment variable, it wins over baseUrl, so check that value too.

A “Change Layout” Button Or “Buy Now” Link Shows On My Site

The floating Change layout button and the “Buy now” links belong to the theme’s own demo. They only appear when the build has PUBLIC_DEMO_MODE=true. Remove that variable from your host’s environment variables or your .env file and deploy again.

Troubleshooting