# Troubleshooting

## 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
1. **Did you change `config.toml`?** The terminal should print `[toml-watcher] ✓ Generated` after you save. If it doesn't, stop `npm run dev` with <kbd>Ctrl</kbd> + <kbd>C</kbd> and start it again. A new language, `trailingSlash`, `defaultLanguage`, and `showDefaultLangInUrl` always need a restart.
2. **Is the dev server running?** The terminal should show `npm run dev` without errors.
3. **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](/ecozen/getting-started/how-ecozen-works/#find-where-any-text-comes-from).
4. **Is the key spelled right?** Misspelled keys are ignored without an error. Compare with the comments in the file.
5. **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](/ecozen/customization/sections/).
6. **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.
7. **Did you edit the right language?** `/fr/` pages read the `french/` files, and `/ar/` pages the `arabic/` files.
8. **Hard-refresh the browser**: <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd> (<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd> 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](/ecozen/customization/pricing/).

### A Menu Item Is Missing
Header and footer items need `"enable": true`. An item without it is hidden. See [Menus](/ecozen/customization/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.

### There Is No Menu On My Phone
`[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](/ecozen/beginner/file-formats/) 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.

### A `[forms]` Warning 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 `your@email.com` 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](/ecozen/customization/forms/#check-the-setup).

### 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](/ecozen/customization/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](/ecozen/customization/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.

<Aside type="tip">
  Still stuck? Contact [support](https://getastrothemes.com/contact/) with the
  exact error message, the command you ran, and your Node.js version
  (`node -v`).
</Aside>