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. 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 almost every Givo 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, as the shipped files do. - 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 Days Left Or “Ended” Are Wrong On The Live Site
- The days left are counted on the day the site is built, not when a visitor opens the page. A site built last week still shows last week’s count. Rebuild and deploy the site every day while an appeal is running: most hosts can run a scheduled build. See Causes & Campaigns.
deadlinemust be a date inYYYY-MM-DDform. On that day the cause says “Last day”; the day after, it says “Ended”. Removedeadlinefor an ongoing cause.- A cause that has “Ended” stays online and still takes gifts. To take it off the site, set
draft: truein its file in every language, and remove its link from the Causes menu.
A Progress Bar Looks Wrong
goal,raised, anddonorsare plain numbers in the cause file:75000, not"75000"or$75,000.- A cause with no
goal(or0) shows an empty bar. A cause that raised more than its goal shows a full bar; the bar never goes past 100%. - The amounts are not live: you update
raisedanddonorsby hand, in every language folder, then rebuild.
The Donation Form Sends Nothing
- The
formblock insrc/content/donate/<language>/-index.mdneeds eithermode: "form"with your provider’sendpoint, ormode: "redirect"withprocessorUrl. Until one is set, the dev server shows a notice inside the form, the build prints a[forms]line, and the form sends nothing. - Set the
formblock in every language’s donate file, not only English. - In redirect mode, check that
{amount},{frequency}, and{cause}inprocessorUrlmatch the names your checkout page expects. - After a gift, your provider should send the donor to
thanksUrl(/donate/thanks/by default).
See Donation Form.
Amounts Differ Between Languages
The donate file of each language has its own copy of the numbers. npm run build prints a [donate] warning that lists the keys that differ: copy the English numbers into the other files. The goals, amounts raised, and deadlines of causes are not checked, so compare those files yourself.
The Phone Number Or Call Link Is Missing
phone in [organization] must be in international form: +, the country code, then digits only ("+15550100199"). Anything else prints an [organization] warning and is ignored, and an empty phone hides every call link.
The Donate Bar On Phones Is Missing
Check [settings.mobileActionBar] in config.toml:
enable = trueturns it on.hideOnlists the pages where it never shows (/donate/by default, which also covers/donate/thanks/, 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 or a dialog is open. That is on purpose.
Event Times Or The Calendar File Are Wrong
startandendin the event file are the local times where the event happens, written2026-11-15T09:00:00.timezonein the event file is the time zone of those times, written like"Europe/Paris". Leave it empty to usetimezonefrom[organization].- Past events leave the upcoming list on their own, at the next build.
“Open Now” Or Office Hours Are Wrong
timezonein[organization]must be your time zone, written like"America/New_York"or"Europe/Paris".- Hours use the 24-hour clock:
"09:00-17:00", or"09:00-12:00,13:00-17:00"for a break. An empty value means closed. Ranges past midnight are not supported. - Days in
closedDates(YYYY-MM-DD) count as closed.
A Menu Item Is Missing
Header items need "enable": true in each src/config/menu.<language>.json; an item without it is hidden. The header’s Causes mega menu is a list you write yourself, so a new cause needs a link there, in every menu file. 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 "HandHeart" or "Droplets".
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 organization 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/photos/my-photo.jpgissrc/assets/images/photos/my-photo.jpg. - Images in Markdown text (
): use a path relative to the content file, as the/components/page does:../../../assets/images/photos/my-photo.jpgfrom a file insrc/content/pages/english/. - Check the exact file name, including upper and lower case and the extension (
.jpgvs.jpeg).
A Form Doesn’t Deliver
- Check
contactFormActionandcontactFormProviderinconfig.toml. The contact, volunteer, and fundraise forms all use them. The shipped address is a placeholder, and the dev server shows a warning inside the form until you change it. - 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.12 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, 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. Plural keys such as donors_two or daysLeft_few in a language that needs them are allowed. 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 in 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; it reads baseUrl only, not SITE_URL.
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.