# 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](/givo/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 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](/givo/getting-started/how-givo-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](/givo/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 languages?** `/fr/` pages read the `french/` files, and `/ar/` pages read the `arabic/` 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).

### 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](/givo/customization/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](/givo/customization/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 = 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](/givo/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 `"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](/givo/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/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 ci` Or `npm install` Fails
- 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-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 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](/givo/customization/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.

<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>