Troubleshooting templates

Template problems show up in four places: when a document is saved, when a sample set is previewed, when a draft is published, and when a workflow renders. Every problem carries a code (DESIGN_…), a path to what caused it and, where possible, a suggested action. Read the code first: it tells you which page of this guide to open.

The document is rejected when saved

A rejected save returns every problem, each with its JSON path ($.pages[0].elements[3].richText) or element (element:5c0d…). Fix all of them and save again.

Code	Cause	Fix
DESIGN_SCHEMA_INVALID	An unknown property, a wrong type, a value out of its range	Compare with the schema (get_json_schema madoo.design-document/2.0); property names are camelCase in documents
DESIGN_ID_DUPLICATE	Two pages, elements, fields or sample sets share an id	Give every id its own GUID — also when you copy an element
DESIGN_PLACEHOLDER_TYPE_MISMATCH	A field type on the wrong element (an image field on a text)	See the field types in Fields and data
DESIGN_PLACEHOLDER_CODE_DUPLICATE	The same code on two elements with a different type, required flag or default	Use one code per value; the same code may appear on several elements only with the same contract (one value fills them all)
DESIGN_BINDING_INVALID	An item. key outside a list, a nested list with its own json field, a link or condition reading a missing field	Read keys only inside their list; a nested list uses sourceCode: "item.<key>" without a field
DESIGN_REPEAT_SOURCE_INVALID	A list whose sourceCode is not a json field of the template (or item.<key> when nested)	Match sourceCode to the list’s field code
DESIGN_REPEAT_CONTINUATION_INVALID	Two lists continuing on new pages on one page, or one inside a Layout	One continue_page list per page, placed directly on the page
DESIGN_RICH_TEXT_INVALID	text differs from the rich text’s content	text = the runs joined, paragraphs separated by \n
DESIGN_LINK_INVALID, DESIGN_CONDITION_INVALID	A scheme other than https/http/mailto/tel; a condition with an unknown operator or field	See Conditions, links and formats
DESIGN_STYLE_INVALID, DESIGN_COMPONENT_INVALID	A property a style kind does not hold (a paint style holds color), an override of a property that cannot be overridden	See Styles and components
DESIGN_MASTER_INVALID	A field, condition or list on a master, or a master of another size	Masters hold static content and apply to pages of their size
DESIGN_RECTANGLE_CORNER_RADIUS_INVALID	A corner radius larger than half the shorter side	Reduce it
DESIGN_SVG_PATH_INVALID	Path data with unsupported commands	Use M L H V C S Q T A Z only

The preview or the render fails

Code	Cause	Fix
DESIGN_PLACEHOLDER_REQUIRED	A required field — or a required key of a list item (items[1].price) — has no value and no default	Send the value; or make the field optional with a default; or use missing_policy: use_template_default on the node
DESIGN_FIELD_UNKNOWN, DESIGN_FIELD_TYPE_INVALID, DESIGN_DATA_INVALID, DESIGN_PLACEHOLDER_TYPE_MISMATCH	The data has a code the template does not have, or a value of the wrong JSON type — a yes/no as "yes", a list as a string (Value for ‘flag’ is not a boolean)	Read the contract; send yes/no as true/false, lists as arrays, numbers as numbers (a number written as text is accepted, but do not rely on it)
DESIGN_REPEAT_OVERFLOW	More rows than fit, with the list’s rule fail	Enlarge the list, shrink the row, or choose fit, clip or continue_page — see Repeated lists
DESIGN_REPEAT_LIMIT_EXCEEDED	More items than maxItems (or the render’s ceiling)	Raise maxItems to the real maximum, or send fewer items
DESIGN_REPEAT_ROW_TOO_TALL	A row that grows is taller than the whole list	Allow fewer lines in the row’s texts, or give the list more height
DESIGN_TEXT_TOO_LONG	A growing text with beyond: fail needs more lines than allowed	Shorten the value, allow more lines, or choose ellipsis or shrink
DESIGN_IMAGE_REQUIRES_ONE_PAGE	output: image with more than one page selected	Select one page, or use output: pages
DESIGN_IMAGE_LIMIT_EXCEEDED, DESIGN_IMAGE_PIXEL_LIMIT_EXCEEDED, DESIGN_IMAGE_TOTAL_LIMIT_EXCEEDED	An image over 20 MiB or 40 million pixels, or over 100 MiB of images in one render	Resize the images before the render
DESIGN_RENDER_LIMIT_EXCEEDED, DESIGN_RENDER_TOO_LARGE	Over 200 pages or 25,000 elements in one render, or a direct render over its limits	Split the document; use a workflow for large outputs
DESIGN_RENDER_BUSY	The renderer is at capacity	Retry after a few seconds (workflows retry by themselves)
FONT_*	A font that cannot be loaded or installed	See Text

Publication is blocked

The readiness check (GET …/draft/publish-readiness) lists blocking errors and warnings:

• a sample set that fails blocks with the error of its render (for example DESIGN_PLACEHOLDER_REQUIRED — Sample “Empty”: Required placeholder ‘title’ is missing): fix the sample set or the template;
• DESIGN_SAMPLE_SET_MISSING and DESIGN_REQUIRED_FIELD_UNEXERCISED warn that the template has no sample set, or that a required field is not covered by one — add a representative value and preview it.

The workflow is rejected or fails on the template node

Code	Cause	Fix
template_field_not_connected (validation)	A required field without default is not connected on Generate PDF or Multi-page PDF	Connect it, or give the field a default in the template
template_not_found, template_revision_not_found, invalid_template_revision	A wrong template_id or a revision that does not exist	Discover templates with list_design_templates, revisions with get_design_template
DESIGN_TEMPLATE_NOT_PINNED, DESIGN_TEMPLATE_PIN_MISMATCH	The node has no published revision fixed, or its pin no longer matches	Set template_id and template_revision (never the internal document fields) and save the workflow again

The render succeeds but the page is wrong

Many problems are warnings: the document is produced, and the layout report says what went wrong. Read it — in the preview’s checks, or in the layout_report output of the workflow node.

Warning	What you see	Fix
DESIGN_TEXT_OVERFLOW	A text cut, ended with …, or shrunk to its minimum	Give it room, a growth rule in a Layout, or a shorter value — see Text
DESIGN_REPEAT_ITEMS_NOT_PRINTED	Fewer rows than items (clip)	Choose another overflow rule if the rows matter
DESIGN_IMAGE_LOAD_FAILED, DESIGN_IMAGE_LOAD_WARNING	An empty image box	The URL is unreachable, private or not an image, or the SVG uses what the renderer cannot draw (an embedded <image>, scripts, web content, more than 2,000 elements); use a storage path or a public HTTPS URL, or simplify the SVG
DESIGN_LINKS_LEFT_OUT, DESIGN_LINKS_OMITTED_FOR_PRINT	A link missing in the PDF	Its address read an empty value; or the PDF is PDF/X-4, which carries no links

And the problems that no check reports:

What you see	Likely cause
A symbol or an accented letter is missing	The font does not contain it — choose another font or remove the character
A text in the wrong font	The family name is misspelt: unknown families print in a substitute font
A price printed as EUR 89.00	The currency format has no currencyDisplay
A gap where a hidden block was	The block is not inside a flowing Layout
Elements below a growing text overlap it	They are not in the same flowing Layout (or, in a list row, not in a Layout inside the row)
A photo cropped in the wrong place	No alignment on the image field, or no focal point on the frame
A style change did not reach an element	The element has a local override of that property, or its values were written by hand without the style command
Every document changed after a template edit	A Generate PDF or Multi-page PDF node without template_revision renders the draft

A method that always works

1. Reproduce with a sample set. Put the failing data in a sample set and run the exact preview: it gives the same result as the workflow, faster, and with the pages to look at.
2. Read the code and the path. The path names the element or the value; the code names the rule.
3. Change one thing, preview again. Keep the sample set: it becomes the test that proves the fix, and protects the template from the same problem later.