Troubleshooting

Kivo Theme Documentation

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

Is the dev server running? The terminal should show npm run dev without errors.
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.
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 teamSection: instead of teamGridSection:, is ignored without an error. Copy the name from the comments in the page file or from Sections.
Is the value one of the allowed ones? In section, contact, FAQ, and pricing files, 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.
Did you edit the other language? /fr/ pages read the french/ files.
Did you change config.toml multilingual settings or trailingSlash? Restart npm run dev.
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.
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.

Header items need "enable": true. An item without it is hidden. See 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 .mdx file fails on a line with {, }, or <: put that text in backticks.

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/ (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 “Unavailable”

That’s normal in npm run dev. 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. See 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.

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

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 Shows On My Site

The floating Change layout button is a demo feature. Set [settings.layoutSwitcher] enable = false in config.toml (the default), and remove PUBLIC_DEMO_MODE if it is set in your host’s environment variables or a .env file.