Errors

Every error Format raises while building your document carries a code. The code is stable across versions; the message is the human-readable explanation. Read the code to recognize the failure mode, and read the message to find the offending element.

This page lists every code, what triggers it, and how to fix it.

Where errors surface

Most errors fire while Format reads the model from your HTML. The document tree is malformed, so the read stops before any page is laid out. A few fire later, during pagination, when the tree parsed cleanly but produced nothing to render. Studio (in your browser) and the API (in production) raise the same codes.

The API masks any internal failure to a single code. A code whose HTTP status is in the 5xx range never reaches the client by its own name; the response carries INTERNAL_SERVER_ERROR and a support reference instead. The 4xx codes below, which describe a fault in the document you sent, pass through unchanged, so you can act on them directly.

If you author and preview in Studio, you catch every parse-time error before it reaches the API.

Document model errors

These fire while Format parses the model from authored HTML. They mean the document tree itself is malformed, not that anything went wrong at render time. Each is a 4xx, so the API returns the code as-is.

NO_DOCUMENT_FOUND

No root <template data-type="document"> exists in the rendered output, so Format found nothing to parse.

This code carries a 5xx status, so the API reports it as INTERNAL_SERVER_ERROR. In normal use the SDK and Studio always emit the Document wrapper, so reaching it means the rendered HTML arrived without a Document root.

INVALID_DOCUMENT

The root <template data-type="document"> is missing a required attribute.

INVALID_LAYOUT

A Layout is missing a required page dimension, or a table of contents sits in the Layout scaffolding instead of inside a Flow.

A Layout id is optional, and Format generates one when you omit it. The id is a non-unique CSS label, so several Layouts may share an id to reuse a design. Sharing an id is no longer an error.

INVALID_FRAME

A Frame is missing its id, or two Frames in the same Layout share an id.

INVALID_VALUE

A page dimension that takes a CSS px length could not be parsed.

Resource errors

These fire while Format inlines stylesheets before rendering. Each is a 4xx, so the API returns the code as-is.

INVALID_HTML_LINK_ELEMENT

A <link> element uses a rel other than stylesheet, whether it sits inside a Layout or directly under the Document.

ASSET_ERROR

A stylesheet Format tried to inline could not be fetched or read. The <link rel="stylesheet"> href, or a CSS @import inside it, pointed at something that failed to load.

INVALID_ASSET_REFERENCE

An asset the document references (an image, font, or stylesheet) failed to load during the render. This is raised by the render pipeline rather than during parsing, so you see it from the API rather than in Studio.

Numbering errors

These fire while Format parses a numbering directive that is missing a required attribute. Each is a 4xx, so the API returns the code as-is. A directive that names a target it cannot resolve does not error; Format reports it instead in the document summary diagnostics, where Studio surfaces it.

Pagination errors

These fire after parsing, while Format lays out pages. They mean the document parsed cleanly but produced nothing to render.

NO_LAYOUT_PROVIDED

The Document parsed, but it holds no Layout. A Document needs at least one Layout to render any pages. This code is a 4xx, so the API returns it as-is.

NO_PAGES_RENDERED

A Layout ran but produced zero pages, because its Flows held no content to lay out. This code is a 4xx, so the API returns it as-is.

PAGE_PROGRESS_STALLED

Pagination produced three empty pages in a row, which means content still queued can never be placed. An empty page always accepts its first item, so a run of empty pages points at content that paints nothing, never a Flow that simply ran long.

This code carries a 5xx status, so the API reports it as INTERNAL_SERVER_ERROR. Format fails loudly here rather than quietly dropping the content it cannot place.

Engine configuration errors

These come from the options passed alongside the document, not from the document itself. In normal use the SDK and Studio set them for you, and both carry a 5xx status, so the API reports them as INTERNAL_SERVER_ERROR.

INVALID_ENGINE_OPTIONS

An engine option is malformed, or a root scope selector matched no element.

INVALID_AUTORUN_OPTIONS

The autorun options that drive Format on the page are malformed.

INTERNAL_ERROR

An internal invariant failed, for example a paginated page missing the key Format wrote to it.

Quick lookup table

A summary of every code, where it comes from, and how the API reports it:

Related

HTML schema reference · Document model · Assets