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 |