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] ✓ Generatedafter you save, except in the Tina edition, which prints it only at startup. If it prints✖ Conversion failed, the file has a format mistake (see File Formats). If it prints nothing, stopnpm run devwith Ctrl + C and start it again.trailingSlash,[settings.multilingual], a new language, andfonts.jsonalways need a restart. - Is the dev server running? The terminal should show
npm run devwithout errors. - Did you edit the right file? A page block overrides the section file, and every Plumbo 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 ofquestionsSection:, 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 languages?
/fr/pages read thefrench/files, and/ar/pages read thearabic/files. - Hard-refresh the browser: Ctrl + Shift + R (⌘ + Shift + R on Mac).
A Section Or Page Disappeared
- Check
enablein the section file and in the page’s block. In a page block, writeenable: true: some blocks (the call to action, the contact section, the logo strip) count as hidden without it. - Check
draftin the page or entry. Drafts show innpm run devbut 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
draftin the collection’s-index.md: it hides the whole collection.
The Phone Number Or Call Button Is Missing
phonein[business]must be in international form:+, the country code, then digits only ("+15550100199"). Anything else prints a[business]warning and is ignored, and an emptyphonehides every call link.- The Call button in the phone bar also needs
showCall = trueunder[settings.mobileActionBar].
The Bottom Bar On Phones Is Missing
Check [settings.mobileActionBar] in config.toml:
enable = trueturns it on.hideOnlists 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
timezonein[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
minLeadDaysafter today and ends aftermaxDays([settings.booking]), and skips the dates inclosedDates.
The Booking Form Says A Postal Code Isn’t Covered
- The code must be listed in
zipsof one of the area files insrc/content/areas/english/(and each other language folder). - The format check is
zipPatternunder[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:hourlyusescallOutFee,hours, andhourlyRate;unitsusesbase,perUnit, andunits. The comment aboverateCardsgives each formula. minimum(optional on a card) raises small totals to the minimum charge, androundingrounds discounted prices (to the nearest 5 by default; use1for exact amounts).- If prices differ from one language to another, their price files differ:
npm run buildprints a[pricing]warning with the keys.
A Menu Item Is Missing
Header items need "enable": true in each src/config/menu.<language>.json; an item without it is hidden. Footer items show unless they say "enable": false. The header’s Services and Areas menus are lists you write yourself, so a new service or area needs a link there. Only the footer areas column fills itself 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
.mdxfile fails on a line with{,}, or<: put that text in backticks. This is also why{phone}and the other business tokens only work in.mdfiles.
Markdown, YAML, TOML & JSON explains each format.
An Image Doesn’t Appear
- Frontmatter images (
image:and similar fields): the file should be insrc/assets/images/and the path must start with/images/./images/areas/my-town.jpgissrc/assets/images/areas/my-town.jpg. - Images in Markdown text (
): the file must be inpublic/, for examplepublic/images/my-photo.jpgfor/images/my-photo.jpg. - Check the exact file name, including upper and lower case and the extension (
.jpgvs.jpeg).
A Form Doesn’t Deliver
- Check
contactFormActionandcontactFormProviderinconfig.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
formActionunder[settings.booking], or tocontactFormActionwhen 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/...), andcontactFormProvider = "formspree". - Netlify: form detection must be on in the Netlify dashboard,
contactFormProvider = "netlify", andcontactFormAction = "/". - Newsletter: the Mailchimp
formActionunder[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 ciOrnpm installFails
- Check
node -v: it must be 22.12 or later. The Tina edition needs version 22 (22.23.4 or later) or 24. - Delete the
node_modulesfolder and runnpm ciagain. - 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-checkFails On Translations
npm run astro-check runs check-i18n first. It fails when a key exists in src/i18n/en.json but not in another language’s file (or the reverse), when a language’s menu has a different structure from the English one, or when a content file exists in one language folder only, or when en.json has a key that no code reads. Add the missing key, menu item, or file to the other language. If you don’t need a language, 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 make sure the build does not set the PUBLIC_DEMO_MODE environment variable, which turns it on. Then build again.