# 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. **Is the dev server running?** The terminal should show `npm run dev` without errors.
2. **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](/consultiz/getting-started/how-consultiz-works/#find-where-any-text-comes-from).
3. **Is the key spelled right?** Misspelled keys in section files are ignored without an error. Compare with a working file.
4. **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](/consultiz/customization/sections/).
5. **Does the page show that section at all?** A block only works where the route renders the section.
6. **Does the page file say `enable: true`?** Then `enable: false` in the section file won't hide it on that page.
7. **Did you edit the other language?** `/fr/` pages read the `french/` files.
8. **Did you change `baseUrl`, `trailingSlash`, a folder name, or the language settings?** Restart `npm run dev`.
9. **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.
- 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]/`.

### A Menu Item Is Missing
Check for `"enable": false` on the item, and on the group or mega menu block it sits in. See [Menus](/consultiz/customization/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](/consultiz/customization/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](/consultiz/customization/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](/consultiz/customization/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.

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