SignalFeed.dev / Guides / How-to

veraPDF PDF/UA-1 errors: what failed on our PDFs and how we fixed them

veraPDF is the free, open-source validator for PDF/A and PDF/UA. It checks the machine-testable parts of PDF/UA-1 (ISO 14289-1) and tells you which clause each failure belongs to. This page covers how to run it and the three failures we hit while building our accessible meeting templates, with the fix for each. Every example PDF in that pack now passes.

Run veraPDF against PDF/UA-1

  • Desktop app: install veraPDF from verapdf.org, open your PDF, choose the PDF/UA-1 profile and click Validate. It runs on Windows, macOS and Linux.
  • Command line: verapdf --flavour ua1 --format html yourfile.pdf > report.html. Use --format text for a one-line PASS or FAIL per file, handy for checking a whole folder.

The report lists each failed rule as a clause number (for example 7.18.1), a short description and how many objects failed it. Fix by clause, not by count: one wrong setting can fail hundreds of objects.

7.4.2: headings that are really paragraphs

Symptom: the document looks fine and its tags panel shows headings, but veraPDF fails clause 7.4.2.

Cause: the exporter wrote custom tag names (here "Heading 1") and then role-mapped them to /P, a plain paragraph, in the document's RoleMap. Assistive technology follows the role map, so screen-reader users get no headings to jump between. We saw this with LibreOffice's tagged PDF export.

Fix: correct the role map so each custom heading tag maps to /H1, /H2 and so on, or export from a tool that writes standard heading tags (Microsoft Word with "Document structure tags for accessibility" turned on). We patch the RoleMap entry directly and save incrementally, then re-validate.

7.18.1: form fields without a description

Symptom: fillable fields fail clause 7.18.1.

Cause: PDF/UA requires each form field to have an accessible name, stored as the field's tooltip (the /TU entry). Many exporters leave it empty, so a screen reader announces only "edit text".

Fix: give every field a tooltip that says what to enter ("Applicant's full name"). In Acrobat that is the field's Properties, General tab, Tooltip. In HTML-to-PDF workflows, a title attribute on each input can be carried into the tooltip.

7.21.4.1: fonts that aren't embedded

Symptom: a PDF that passed starts failing clause 7.21.4.1 after you edit form fields.

Cause: PDF/UA requires every font to be embedded. When a tool regenerates a field's appearance it may use a standard font such as ZapfDingbats or Helvetica without embedding it. In our case the regeneration step itself introduced the failure.

Fix: turn on the exporter's option to embed standard fonts, and change field properties without regenerating appearances where possible. Re-run veraPDF after every edit, not only at the end.

Other common PDF/UA-1 failures

  • 7.1 (document): missing PDF/UA identifier in the metadata, no document title, or the viewer set to show the file name instead of the title (DisplayDocTitle).
  • 7.2 (text): no document language, or content outside the tag tree that isn't marked as an artifact.
  • 7.3 (graphics): Figure tags without alternate text.
  • 7.5 (tables): table header cells that aren't tagged TH, or have no scope.

What a pass does and doesn't prove

veraPDF checks structure that a machine can test. It cannot judge whether alt text is accurate, whether the reading order makes sense, or whether link text is meaningful. The Matterhorn Protocol lists the PDF/UA failure conditions, and many of them need human review. Use veraPDF as the gate, then check reading order and alt text by hand. For a quick first look without installing anything, try our in-browser PDF check.

Want a veraPDF report on your PDF?

Email one PDF and get the veraPDF PDF/UA-1 report back free, with a plain-English list of what to fix. Remediation is available on Upwork, or email aaron.signalfeed@gmail.com.

Sources