Skip to content
New: Customize your theme with an AI assistant. Read the guide

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). 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.
  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 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.
  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.
  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 languages? /fr/ pages read the french/ files, and /ar/ pages read the arabic/ files.
  8. Hard-refresh the browser: Ctrl + Shift + R (⌘ + Shift + R on Mac).

A Section Or Page Disappeared

  • Check enable in the section file and in the page’s block. In a page block, write enable: true, as the shipped files do.
  • 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 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.
  • deadline must be a date in YYYY-MM-DD form. On that day the cause says “Last day”; the day after, it says “Ended”. Remove deadline for an ongoing cause.
  • A cause that has “Ended” stays online and still takes gifts. To take it off the site, set draft: true in its file in every language, and remove its link from the Causes menu.

A Progress Bar Looks Wrong

  • goal, raised, and donors are plain numbers in the cause file: 75000, not "75000" or $75,000.
  • A cause with no goal (or 0) 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 raised and donors by hand, in every language folder, then rebuild.

The Donation Form Sends Nothing

  • The form block in src/content/donate/<language>/-index.md needs either mode: "form" with your provider’s endpoint, or mode: "redirect" with processorUrl. 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 form block in every language’s donate file, not only English.
  • In redirect mode, check that {amount}, {frequency}, and {cause} in processorUrl match 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.

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 = true turns it on.
  • hideOn lists 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

  • start and end in the event file are the local times where the event happens, written 2026-11-15T09:00:00.
  • timezone in the event file is the time zone of those times, written like "Europe/Paris". Leave it empty to use timezone from [organization].
  • Past events leave the upcoming list on their own, at the next build.

“Open Now” Or Office Hours Are Wrong

  • timezone in [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 .mdx file fails on a line with {, }, or <: put that text in backticks. This is also why {phone} and the other organization 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/photos/my-photo.jpg is src/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.jpg from a file in src/content/pages/english/.
  • 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 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/...), 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 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_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-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.

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.

Type something to search...