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

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.
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, 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.
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 Sections.
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.
Did you edit the other languages? /fr/ pages read the french/ files, and /ar/ pages read the arabic/ files.
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.
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.

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 and Navigation.

An Icon Doesn’t Show

The icon name doesn’t exist in Lucide. Copy the exact name from 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 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.

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.

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

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.

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.

Troubleshooting