Documentation

Troubleshooting

Common gotchas when building content with the MCP tools, and how to fix them

Most problems when building content through the MCP tools come from a handful of recurring mistakes. This page lists the ones that actually bite, each with its fix.

Gotchas

Symptom	Fix
Build is slow	You're uploading and converting images, or creating an empty page and then updating it. Attach images inline with a `sourceUrl` ingest and send a single `page_create` carrying all elements.
`imgBroken > 0` after ingest	The `sourceUrl` is wrong or unreachable, or you passed an `f_cover`-style option. Check the URL is fetchable, and remember `f_` sets the format only, never the fit — use CSS `object-fit: cover` for cropping.
Blank page after building	Create the page with `renderMode: "dynamic"`. A page that was prerendered while it was still empty stays blank.
`{{ relations.image }}` renders nothing	Bind the relation first, then pass the bound file to `image_path`: `{{#if relations.image as file}}<img src="{{ image_path(file, "w_900,f_webp") }}">{{/if}}`.
`file_upload_multipart` returns `failedIndices`	This path is only for local-only images (no `sourceUrl`). Resend only the failed parts; `-strip` the image and keep parts ≤ ~1.5 KB so they pass first try. Prefer `sourceUrl` on `file_upload` whenever the image is reachable by URL.
Builder rows read as `item.title`	Row values live under `item.data.title` — each row is `{ id, data: { … } }`. In the property definition the row-template's `data` and `defaultValue` must be `""`.
Duplicated elements on update	Resend both `id` and `tempId` on every element, including existing ones. To remove an element, drop it from `elements` and add its numeric id to `deletedElements`.
A bare icon name doesn't render	Prefix it with `tabler:` (e.g. `tabler:calendar`). A bare word does not resolve.
Nav / Footer (or styles) render twice	They live in both the layout and `page.elements`. Shared components belong in the layout only; the page carries just its own section elements.
Layout renders but page content is missing	The layout is missing the `PageContent` element (or `{{ render_elements(page.layout.elements) }}` in its template), or the page has no `layoutId`.
`layout_create` returns a DB error	The instance has no layout table. Use the no-layout fallback: put Nav/Footer, global styles and site scripts as page elements, and font links in the page template.

Many of these are covered in more depth in the Tools Reference callouts — check there for the exact payload shapes.