Skip to content

Diagnostic codes

Every result carries the diagnostics of its call. The code is stable; the message is for people and its wording may change. A code with a category fails the call in strict mode when that category is selected; a code without one never fails a call. The url column says what the diagnostic's url field holds.

Code Severity Strict category When url
resource.not-found warning missing-resources A file: URL names no file, or an HTTP response has a status of 400 or above The resource URL
resource.denied warning missing-resources The access policy refused the URL, also after a redirect The resource URL
resource.timeout warning missing-resources The fetch took longer than timeout The resource URL
resource.too-large warning missing-resources The resource is larger than max_resource_size The resource URL
resource.unsupported warning missing-resources The URL's scheme is not one the fetcher handles The resource URL
resource.unresolved warning missing-resources A relative reference without a base URL None (the reference is in the message)
resource.failed warning missing-resources Any other fetch failure (connection refused, I/O error, an error from a custom fetcher) The resource URL
resource.invalid warning missing-resources The resource was loaded but cannot be used (an image or font that does not decode, a linked stylesheet whose content type is not text/css) The resource URL
glyph.missing warning missing-glyphs No available face has a glyph for a character that is shown None
tags.missing-alt warning tags Tagged output: an img, or an element of role img, has no alt text None
tags.missing-title warning tags ua-1 or ua-2: the PDF has no title None
tags.missing-language warning tags ua-1 or ua-2: the PDF has no language None
overflow.page info overflow Content extends beyond the page box None
css.syntax warning none A CSS parse error (a rule or declaration dropped by error recovery) None
css.unknown-property warning none A declaration of a property the engine does not know None
css.invalid-value warning none A declaration whose value is invalid for its property None
css.invalid-selector warning none A selector that is invalid or not supported None
html.duplicate-id warning none An id value used by a second element None
link.missing-anchor warning none An internal link #name whose target does not exist None
pdf.page-out-of-range warning none A pages item beyond the last page None

Strict-mode categories

The category names are the same in Rust (StrictFlags), Python (Options(strict=...)) and on the command line (--strict=LIST): missing-resources, missing-glyphs, tags, overflow. --strict without a list, and strict=True, select all of them.

Failure lines of the command line

When a run fails for another reason than strict mode, the last line printed names the failure. With --diagnostics json it is an object with one of these codes:

Code Failure
error.fetch the input, a user stylesheet or an attachment cannot be loaded; url names it
error.parse an option value does not parse
error.pdf the PDF cannot be produced (no page selected, an attachment with PDF/A-2b, the writer failed)
error.io the output cannot be written