Dokumentation
Fehlerbehebung
Häufige Stolperfallen beim Erstellen von Inhalten mit den MCP-Tools und wie du sie behebst
Die meisten Probleme beim Erstellen von Inhalten über die MCP-Tools entstehen durch eine Handvoll wiederkehrender Fehler. Diese Seite listet die auf, die wirklich wehtun, jeweils mit der passenden Lösung.
Stolperfallen
| Symptom | Lösung |
|---|---|
| Build ist langsam | Du lädst Bilder hoch und konvertierst sie, oder du erstellst eine leere Seite und aktualisierst sie danach. Hänge Bilder inline per sourceUrl-Ingest an und schicke ein einziges page_create mit allen Elementen. |
imgBroken > 0 nach dem Ingest | Die sourceUrl ist falsch oder nicht erreichbar, oder du hast eine f_cover-artige Option übergeben. Prüfe, ob die URL abrufbar ist, und denk daran: f_ legt nur das Format fest, nie den Zuschnitt — nutze für den Zuschnitt CSS object-fit: cover. |
| Leere Seite nach dem Build | Erstelle die Seite mit renderMode: "dynamic". Eine Seite, die prerendered wurde, während sie noch leer war, bleibt leer. |
{{ relations.image }} zeigt nichts an | Binde die Relation zuerst, dann übergib die gebundene Datei an image_path: {{#if relations.image as file}}<img src="{{ image_path(file, "w_900,f_webp") }}">{{/if}}. |
file_upload_multipart liefert failedIndices | Dieser Weg ist nur für rein lokale Bilder (ohne sourceUrl). Schicke nur die fehlgeschlagenen Teile erneut; -strip das Bild und halte die Teile ≤ ~1,5 KB, damit sie beim ersten Versuch durchgehen. Bevorzuge sourceUrl bei file_upload, wann immer das Bild per URL erreichbar ist. |
Builder-Zeilen werden als item.title gelesen | Zeilenwerte liegen unter item.data.title — jede Zeile ist { id, data: { … } }. In der Property-Definition müssen data und defaultValue der Zeilenvorlage "" sein. |
| Doppelte Elemente beim Update | Schicke bei jedem Element sowohl id als auch tempId mit, auch bei bestehenden. Um ein Element zu entfernen, lass es aus elements weg und füge seine numerische id zu deletedElements hinzu. |
| Ein blanker Icon-Name wird nicht angezeigt | Stell tabler: voran (z. B. tabler:calendar). Ein blankes Wort wird nicht aufgelöst. |
| Nav / Footer (oder Styles) werden doppelt gerendert | Sie stehen sowohl im Layout als auch in page.elements. Gemeinsame Components gehören nur ins Layout; die Seite trägt nur ihre eigenen Abschnitts-Elemente. |
| Layout rendert, aber der Seiteninhalt fehlt | Dem Layout fehlt das PageContent-Element (oder {{ render_elements(page.layout.elements) }} in seinem Template), oder die Seite hat keine layoutId. |
layout_create liefert einen DB-Fehler | Die Instanz hat keine Layout-Tabelle. Nutze den No-Layout-Fallback: Nav/Footer, globale Styles und Site-Scripts als Seiten-Elemente, Font-Links ins Seiten-Template. |
Viele dieser Punkte sind ausführlicher in den Callouts der
Tools-Referenz beschrieben — dort findest du die
genauen Payload-Formen.