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 prints ✖ Conversion failed, the file has a format mistake (see File Formats). If it prints nothing, stop npm run dev with Ctrl + C and start it again. trailingSlash, [settings.multilingual], a new language, and fonts.json 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 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.
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 faqSection: instead of questionsSection:, is ignored without an error. Copy the name from Sections.
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.
Did you edit the other language? /fr/ pages read the french/ files.
Hard-refresh the browser: Ctrl + Shift + R (⌘ + Shift + R 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.

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.

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.

An Icon Doesn’t Show

The icon name doesn’t exist in Lucide. Copy the exact name from 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 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 & 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.

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.

Troubleshooting