# 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. **Is the dev server running?** The terminal should show `npm run dev` without errors.
2. **Did you edit the right file?** A page block overrides the section file. Search the project for the old text to find where it really comes from: see [Find Where Any Text Comes From](/taskly/getting-started/how-taskly-works/#find-where-any-text-comes-from).
3. **Is the key spelled right?** Misspelled keys are ignored without an error. Compare with the comments in the file.
4. **Is the page block named right?** A block with a wrong name, for example `faq:` instead of `faqSection:`, is ignored without an error. Copy the name from the comments in the page file or from [Sections](/taskly/customization/sections/).
5. **Is the key in the right place?** `layout` sits at the top level of a section block (`heroSection: layout: "split"`), not under `options:`. A key in the wrong place is ignored.
6. **Did you edit the other language?** `/fr/` pages read the `french/` files.
7. **Did you change `config.toml` multilingual settings or `trailingSlash`?** Restart `npm run dev`.
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.
- 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`.

### A Menu Item Is Missing
Header items need `"enable": true`. An item without it is hidden. See [Menus](/taskly/customization/menus/).

### 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 error that names a section field**, such as `layout` or `color` with a list of allowed values: the value in the section file or page block is not one of them. Copy one from the comment next to the field.
- **An `.mdx` file fails on a line with `{`, `}`, or `<`:** put that text in backticks.

[Markdown, YAML, TOML & JSON](/taskly/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/` (`public/images/` also works) and the path must start with `/images/`.
- **Images in Markdown text** (`![...](...)`): the file must be in `public/`, for example `public/images/gallery/1.jpg` for `/images/gallery/1.jpg`.
- Check the exact file name, including upper and lower case and the extension (`.jpg` vs `.jpeg`).

### Search Says It Works On The Built Site
That's normal in `npm run dev`: there is no search index yet. Search works after `npm run build`: test it with `npm run preview`.

### Forms Show A Warning
The warning appears in `npm run dev` until the form has a real endpoint. Set `contactFormAction` and `[settings.subscription] formAction` in `config.toml`, or `form.action` in the auth files (the contact and demo forms also accept their own `form.action` in their section files). See [Forms](/taskly/customization/forms/).

### The Contact Form Doesn't Deliver
- **Formsubmit:** confirm the activation email it sends after the first message.
- **Netlify:** form detection must be on in the Netlify dashboard, and `contactFormProvider = "netlify"`.
- Test from the live site, not from `localhost`.

### `npm run dev` Never Starts (Windows)
If the terminal stops at `[toml-watcher] Watching config.toml for changes...`, run the two parts in two terminals: `npm run toml:watch -- --watch` and `npx astro dev`. See [Installation](/taskly/getting-started/installation/).

### `npm ci` Or `npm install` Fails
- Check `node -v`: it must be 22.12.0 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 (just before the `page(s) built` line) 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](/taskly/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.

### A "Change Layout" Button Or "Buy Now" Link Shows On My Site
The floating **Change layout** button and the "Buy now" links belong to the theme's own demo. They only appear when the build has `PUBLIC_DEMO_MODE=true`. Remove that variable from your host's environment variables or your `.env` file and deploy 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>