# 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](/margo/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 every Margo homepage has page blocks. Search the project for the old text to find where it really comes from: see [How Margo Works](/margo/getting-started/how-margo-works/).
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 `teamSection:` instead of `teamGridSection:`, is ignored without an error. Copy the name from [Sections](/margo/customization/sections/).
6. **Is the value one of the allowed ones?** In the files in `sections/`, `contact/`, `faq/`, and `pricing/`, a misspelled value such as a layout name isn't reported, and the section may fall back to its default look. 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.
- The call to action above the footer also hides when its `title` is empty.
- 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.

### A Project Card Is Missing From The Homepage
The hero cards and some project lists name projects by id, such as `cards: ["ceramic-forms", ...]`. Each id must match a file name in `src/content/projects/<language>/`, without `.md`. If you renamed or deleted a project, update its id everywhere you find it, in every language. See [Projects](/margo/customization/projects/).

### A Menu Item Is Missing
The menus are lists you write yourself in each `src/config/menu.<language>.json`, so a new project, service, or page needs a link there if you want one, in every language. Then check:

- **`"enable": false`** hides an item, and everything inside it. An item without `enable` shows.
- **The order** is the order of the file. A `weight` number doesn't move an item.
- **The Search link** in the Pages menu shows only while `[settings.search] enable` is `true`.
- **The project card** in the Services menu disappears when `cta.project` names a project file that doesn't exist, or when it is empty and no project has `featured: true`.
- **An item is missing on one language only:** that language's file is missing the item, or has it under another name. Compare it with `menu.en.json`.

See [Menus](/margo/customization/menus/) and [Navigation](/margo/features/navigation/).

### 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 `"PenTool"` or `"Camera"`.

### 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 image block needs a `src` and an `alt`":** each item in a project's `images` list needs both, unless it is a `type: "text"` block, which needs a `body`.
- **An `.mdx` file fails on a line with `{`, `}`, or `<`:** put that text in backticks.

[Markdown, YAML, TOML & JSON](/margo/beginner/file-formats/) explains each format.

### An Image Doesn't Appear
- **Frontmatter images** (`image:`, `src:`, and similar fields): put the file in `src/assets/images/` and write the path from `/images/`. `/images/projects/my-project/cover.jpg` is `src/assets/images/projects/my-project/cover.jpg`.
- Check the exact file name, including upper and lower case and the extension (`.jpg` vs `.jpeg`).

### Search Says It Is Unavailable
That's normal in `npm run dev`. The search index is made at the end of `npm run build`: test it with `npm run preview`. See [Search](/margo/customization/search/).

### Forms Show A Warning
The warning appears in `npm run dev` until the form has a real endpoint. Set `contactFormAction` and `contactFormProvider` in `[settings]` of `config.toml`, and `formAction` under `[settings.subscription]` for the newsletter. See [Forms](/margo/customization/forms/).

### The Contact Form Doesn't Deliver
- **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.

### "Book A Call" Opens The Contact Page
Every **Book a call** button goes to `booking` under `[settings.contactInfo]`, which is `/contact/` until you change it. Set it to your scheduling page (a full `https://` address). See [Contact & Booking](/margo/customization/contact-booking/).

### The Contact Dock Doesn't Show
The dock is off by default: set `enable = true` under `[settings.contactDock]`. A page can turn it on or off for itself with `contactDock: true` or `false` in its frontmatter. It appears once the first section has scrolled away, and hides while the footer is in view. That is on purpose.

### `npm ci` Or `npm install` Fails
- Check `node -v`: it must be 22.23.4 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.

### 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. See [SEO & AI Visibility](/margo/customization/seo-ai-visibility/).

### 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: leave it unset. 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>