# 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 prints `✖ Conversion failed`, the file has a format mistake (see [File Formats](/homio/beginner/file-formats/)). If it prints nothing, stop `npm run dev` with <kbd>Ctrl</kbd> + <kbd>C</kbd> and start it again. `trailingSlash`, `[settings.multilingual]`, a new language, and `fonts.json` 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 every Homio page, the homepages included, has page blocks. Search the project for the old text to find where it really comes from: see [Find Where Any Text Comes From](/homio/getting-started/how-homio-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 `faqSection:` instead of `questionsSection:`, is ignored without an error. Copy the name from [Sections](/homio/customization/sections/).
6. **Is the value one of the allowed ones?** In section files and the contact page file, 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 other language?** `/fr/` pages read the `french/` 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).

### `npm run dev` Never Opens The Site On Windows
The Windows command prompt runs the two parts of `npm run dev` one after the other, so Astro never starts. Use two terminals: `npm run toml:watch -- --watch` in the first, then `npx astro dev` in the second. See [Installation](/homio/getting-started/installation/).

### 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 (the call to action, the contact section, the logo strip) 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`: it hides the whole collection.

### The Phone Number Or Call Button Is Missing
- `phone` in `[business]` must be in international form: `+`, the country code, then digits only (`"+15550100199"`). Anything else prints a `[business]` warning and is ignored, and an empty `phone` hides every call link.
- The **Call** button in the phone bar also needs `showCall = true` under `[settings.mobileActionBar]`.

### The Bottom Bar On Phones Is Missing
Check `[settings.mobileActionBar]` in `config.toml`:

- `enable = true` turns it on.
- `hideOn` lists the pages where it never shows (`/book/` and `/contact/` by default, since those pages already have the form).
- With `hideNearFooter = true`, it slides away while the footer is in view. It also hides while a form field has focus and while the menu is open. That is on purpose.

### "Open Now" Or Booking Dates Are Wrong
- `timezone` in `[business]` must be your time zone, written like `"America/New_York"` or `"Europe/Paris"`.
- Hours use the 24-hour clock: `"07:30-18:00"`, or `"08:00-12:00,13:00-17:00"` for a break. An empty value means closed. Ranges past midnight are not supported.
- The booking calendar starts `minLeadDays` after today and ends after `maxDays` (`[settings.booking]`), and skips the dates in `closedDates`.

### The Booking Form Says A Postal Code Isn't Covered
- The code must be listed in `zips` of one of the area files in `src/content/areas/english/` (and `french/`).
- The format check is `zipPattern` under `[settings.booking]`. The default only accepts 5 digits; the comment there shows a UK pattern.
- To stop the area check, set `checkArea = false`.

### The Estimator Shows Odd Prices
- Every price is a plain number in `src/content/pricing/english/-index.md`: `70`, not `"70"` or `$70`.
- Check the card's `mode`: `rooms` uses `base`, `perBedroom`, and `perBathroom`; `hourly` uses the call-out fee, hours, and hourly rate; `units` uses `base` and `perUnit`. The comment above `rateCards` gives each formula.
- `minimum` raises small totals to the minimum charge, and `rounding` rounds discounted prices (to the nearest 5 by default; use `1` for exact amounts).
- If English and French show different prices, the two price files differ: `npm run build` prints a `[pricing]` warning with the keys.

### A Menu Item Is Missing
Header items need `"enable": true` in `src/config/menu.en.json` (and `menu.fr.json`); an item without it is hidden. Footer items show unless they say `"enable": false`. The **Areas** menu and the footer areas column fill themselves from your area files. See [Menus](/homio/customization/menus/).

### An Icon Doesn't Show
The icon name doesn't exist in Lucide. Copy the exact name from [lucide.dev/icons](https://lucide.dev/icons/), for example `"Wrench"` or `"Building2"`.

### 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. This is also why `{phone}` and the other business tokens only work in `.md` files.

[Markdown, YAML, TOML & JSON](/homio/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/areas/my-town.jpg` is `src/assets/images/areas/my-town.jpg`.
- **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`).

### A Form Doesn't Deliver
- Check `contactFormAction` and `contactFormProvider` in `config.toml`. The shipped address is a placeholder, and the dev server shows a warning inside the form until you change it.
- Booking requests go to `formAction` under `[settings.booking]`, or to `contactFormAction` when it is empty. Both use the same provider.
- **Formsubmit:** confirm the activation email it sends after the first message.
- **Formspree:** the address must be your form's own endpoint (`https://formspree.io/f/...`), and `contactFormProvider = "formspree"`.
- **Netlify:** form detection must be on in the Netlify dashboard, `contactFormProvider = "netlify"`, and `contactFormAction = "/"`.
- **Newsletter:** the Mailchimp `formAction` under `[settings.subscription]` must be your list's URL, with every `&amp;` from the embed code changed to `&`.
- Test from the live site after each change.

### `npm ci` Or `npm install` Fails
- Check `node -v`: it must be 22.12 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.

### `astro-check` Fails On Translations
`npm run astro-check` runs `check-i18n` first. It fails when a key exists in `src/i18n/en.json` but not in `fr.json` (or the reverse), when the French menu has a different structure from the English one, or when a content file exists in one language folder only. Add the missing key, menu item, or file to the other language. If you don't need French, see [Internationalization](/homio/customization/internationalization/).

### The Build Warns About The Site URL
A yellow `[site] The site URL is still a placeholder` line 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.

### 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. After you change the logo, tagline, or description, run `npm run generate-og-image` to redraw the shared social image.

### A "Change Layout" Button Shows On My Site
That button is the theme demo's layout switcher. Set `enable = false` under `[settings.layoutSwitcher]` in `config.toml`, and remove `PUBLIC_DEMO_MODE` from your host's environment variables or your `.env` file if it is there. Then build 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>