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

Did you change config.toml? The terminal should print [toml-watcher] ✓ Generated after you save. If it doesn’t, stop npm run dev with Ctrl + C and start it again. A new language, trailingSlash, defaultLanguage, and showDefaultLangInUrl always need a restart.
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, and the main homepage reads only the section files (apart from its ctaSection block). 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 faqsSection: instead of faqSection:, is ignored without an error. Copy the name from Sections.
Is the value one of the allowed ones? In section, about, contact, FAQ, pricing, and calculator files, a misspelled value such as a layout name isn’t reported. Copy the value from the comment next to it.
Did you edit the right language? /fr/ pages read the french/ files, and /ar/ pages the arabic/ files.
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. In a page block, write enable: true: some blocks count as hidden without it.
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.

A Pricing Package Is Missing

Every package in pricing-section.md needs enable: true. A package without it is hidden. See Pricing.

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

An Icon Shows As A Placeholder

The icon name doesn’t exist in Lucide, or isn’t in PascalCase. Write "BatteryCharging", not "battery-charging" or "Battery Charging". The browser console names the icon it couldn’t find.

[settings.headerOffcanvas] enable must be true in config.toml: the slide-in panel is the mobile menu.

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 .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/ and the path must start with /images/.
Images in Markdown text (![...](...)): the file must be in public/, for example public/images/my-photo.jpg for /images/my-photo.jpg.
Check the exact file name, including upper and lower case and the extension (.jpg vs .jpeg).

The Quote Form Doesn’t Deliver

Check contactFormAction and contactFormProvider in config.toml. The shipped address is a placeholder. If the terminal shows a [forms] line, start with the section below.
Formsubmit: confirm the activation email it sends after the first request.
Formspree: contactFormAction must be your form’s own endpoint (https://formspree.io/f/...), and contactFormProvider = "formspree". Check the submissions in your Formspree dashboard.
Netlify: form detection must be on in the Netlify dashboard, contactFormProvider = "netlify", and contactFormAction = "/".
Test from the live site after each change.

AWarning Or “Form Not Connected” Note

A line with a yellow [forms] tag in the npm run dev or npm run build output, or a “Dev only · form not connected” note inside a form after you submit it on the dev server, means a form address isn’t set up yet. The line names the form and the problem:

contact: set contactFormAction and contactFormProvider in [settings] of config.toml. This covers the quote form, the contact band form, and the form hero.
newsletter: set action and provider in [settings.newsletter].
“still a placeholder”: replace the shipped [email protected] address with your own.
“does not look like a … endpoint”: the address doesn’t match the provider. Formsubmit needs https://formsubmit.co/..., Formspree https://formspree.io/f/..., and Netlify "/".
“unknown provider”: use formsubmit.co, formspree, or netlify (or "" for the newsletter).

The note never shows on a built or deployed site. Once you save a working address in config.toml, the note stops appearing and the next build prints no [forms] line. See Forms.

The Calculator Shows Odd Numbers

Check the values under calculator.assumptions in calculator-section.md: they must be plain numbers (0.28, not "0.28" or 0,28), and performanceRatio and coverageTarget are between 0 and 1. Work out one result by hand with the formula in Savings Calculator.

`npm ci`Or`npm install`Fails

Check node -v: it must be 22.23.4 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 line that starts with a yellow [site] tag and says The site URL is still a placeholder at the end of the npm run build output 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.

Troubleshooting