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 in section files are ignored without an error. Compare with a working file.
Is the page block named right? A block with a wrong name is ignored without an error. Copy the name from the page file’s comments or from Sections.
Does the page show that section at all? A block only works where the route renders the section.
Does the page file say enable: true? Then enable: false in the section file won’t hide it on that page.
Did you edit the other language? /fr/ pages read the french/ files.
Did you change baseUrl, trailingSlash, a folder name, or the language settings? 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 options.limit: 0 hides a preview section, and an empty list (list: [], articles: []) hides logos and article sections.
Check draft in the page or entry. Drafts show in npm run dev but not on the built site. draft: true in a collection’s -index.md hides the whole collection.
Check that the section’s line is still in the route file in src/pages/[...lang]/.

Check for "enable": false on the item, and on the group or mega menu block it sits in. See Menus.

The Site Shows An Error After I Edited A File

TOML: the terminal names the line in config.toml. Check for a missing quote or a key outside its [table].
YAML (frontmatter): check indentation (spaces, no tabs), quotes around text with : or #, and that list items start with - .
JSON (menus, i18n, fonts): 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 .mdx file fails on a line with {, }, or <: put that text in backticks.

An Image Doesn’t Appear

The path must start with /images/, and the file must be in src/assets/images/ or public/images/ under that path.
Check the exact file name, including upper and lower case and the extension (.webp vs .jpg).
If you replaced an image in public/images/ but the old one still shows, a file with the same path exists in src/assets/images/, and that one wins. Use a new file name. See Icons & Images.

A Form Says It Is Not Configured

That is the default. Set contactFormAction (contact forms), [settings.subscription] formAction (footer newsletter), or formAction in newsletter.md (newsletter section). 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.

Search Isn’t In The Header

It is hidden until you set [settings.headerActions] exploreUrl, for example to "/search/".

The Build Warns About The Site URL

A yellow [site] The site URL is not set line at the end of npm run build means [site] baseUrl is empty. Set it to your real address in config.toml, or set a SITE_URL environment variable for the build. Without it there is no sitemap. See SEO & AI Visibility.

`npm run verify`Fails At The Formatting Step

Run npm run format, or npx prettier --write path/to/file for one file, then run npm run verify again.

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

Troubleshooting