pdfua_validation_failed

HTTP 422 · code: "pdfua_validation_failed" · type: https://docs.formfeed.dev/errors/pdfua-validation-failed

The render set pdf.ua with the strict check, and the finished file fails at least one of the machine-checkable rules of PDF/UA-1. Nothing is delivered: a file that was asked for as PDF/UA-1 never comes back as a plain PDF instead.

accessibility.failures lists each rule that failed: its number in the validator's rule set, what to change in the template, and the start tags of the elements it is about. The render is failed and keeps the same block, so GET /renders/{id} and the render log show it later. No file is stored, and a failed render costs nothing.

Where the render was also an e-invoice, the problem carries einvoice beside accessibility: the invoice itself was valid, and the file it was converted to is the one that failed PDF/UA-1. No e-invoice is delivered either.

Example

{
  "type": "https://docs.formfeed.dev/errors/pdfua-validation-failed",
  "title": "PDF/UA validation failed",
  "status": 422,
  "detail": "The PDF fails 1 of the 106 machine-checkable rules of PDF/UA-1 (7.4.2-1)",
  "code": "pdfua_validation_failed",
  "location": null,
  "render_id": "rnd_7da09ab6cd9946b798c187c2a9350852",
  "accessibility": {
    "standard": "PDF/UA-1",
    "check": "strict",
    "conformant": false,
    "validator": "veraPDF 1.30.2",
    "rules": { "passed": 105, "failed": 1 },
    "failures": [
      {
        "rule": "7.4.2-1",
        "code": "heading-order",
        "count": 1,
        "message": "This h3 follows an h1, so a heading level is skipped. Make it an h2 and size it with CSS.",
        "elements": ["<h3 class=\"section\">"]
      }
    ],
    "warnings": []
  },
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Common causes

• A heading level is skipped (heading-order): an h3 straight after an h1, or a document that starts with an h2. Headings chosen for their size are the usual reason.
• An image has no alt attribute (image-alt), or a chart, a canvas or an svg with role="img" has no name (figure-name).
• The document has no title (document-title): no pdf.metadata.title in the settings and no <title>.
• The rows of a table span different numbers of columns (table-rows), often because of a colspan that does not add up.
• A data cell of a table is empty (table-cell-empty). The browser writes no cell for an empty td, so the row is shorter in the file than in the markup; a non-breaking space in the cell is enough.
• Text sits under a CSS mask (masked-text).

A failure without a code is a rule the template check has no finding for; its message is the validator's own description of the rule.

How to fix it

• Change the template as message says. elements shows which tags are meant.
• In the editor, turn on Accessible PDF (PDF/UA-1) in the Document section of the page setup. The Flow and Paged previews then check the page and list each finding under Problems, at its line, before anything is rendered.
• formfeed validate reports what the source alone already shows: a missing title, an image without alt.
• To get the file while you fix the template, set the check to report: "pdf": { "ua": { "check": "report" } }. The render then succeeds, the file is delivered without the PDF/UA identifier, and accessibility.conformant is false.

Accessible PDFs explains each finding and what the check does and does not prove.

Retry?

No. Retrying the same request gives the same answer; change the template or the data first. Send the corrected request with a new Idempotency-Key or without one: a 4xx answer is stored under its key for 24 hours, so the old key returns this problem again. See retrying.