Troubleshooting: PDF/A and PDF/UA validation failures

Scope

These entries cover failures the engine raises while keeping a document within a Portable Document Format/Archive (PDF/A) or Portable Document Format/Universal Accessibility (PDF/UA) profile. The clause numbers below come from the engine’s source and exception messages. This page paraphrases them. The engine reports profile failures that it detects; it does not certify document conformance. Use an external validator with its own rule set for the authoritative conformance verdict.

Entry: encryption is refused under PDF/A

• Symptom. NextPDF\Security\Exception\IncompatiblePdfAModeException with a message that says an encryption operation is forbidden in a PDF/A mode.
• Likely cause. The pipeline enabled a PDF/A mode and requested encryption. The engine cites International Organization for Standardization (ISO) 19005-{1,2,3,4} §6.1.3: the Encrypt key must not be present in the trailer of a PDF/A file. The engine refuses this combination absolutely, regardless of call order.
• Evidence / diagnosis. getContext() returns pdfa_mode and encryption_operation. The failure-path test tests/SecurityScenarios/PdfAEncryptionRefusalTest.php asserts that the refusal fires whether you enable PDF/A before or after the encryption call.
• Resolution.
  1. Decide what the document needs: archival conformance or encryption.
  2. For an archival document, remove the encryption call.
  3. For an encrypted document, remove the PDF/A enable call.
  4. Run the pipeline again.
• Related. Encryption and permissions.

Entry: image filter is forbidden under PDF/A-1

• Symptom. Pdf14FeatureRejectedException during image ingestion, with a message that names /JPXDecode or /JBIG2Decode and the clause ISO 19005-1:2005 §6.1.13.
• Likely cause. A PDF/A-1 build ingested an image that uses a filter introduced after PDF 1.4. PDF/A-1 targets the PDF 1.4 feature set, so PdfA1FeatureGuard rejects Joint Photographic Experts Group (JPEG) 2000 (/JPXDecode) and JBIG2 (/JBIG2Decode).
• Evidence / diagnosis. src/Writer/PdfA1FeatureGuard.php contains the forbidden-filter list and raises the cited clause. The guard rejects these filters only under the PDF/A-1 profile; PDF/A-2, PDF/A-3, and the PDF 2.0 profile permit them.
• Resolution.
  1. Re-encode the source image without JPEG 2000 or JBIG2. For example, re-save it as a baseline JPEG or a Flate-compressed image.
  2. Alternatively, target PDF/A-2 or PDF/A-3, which permit those filters.
  3. Run the build again.
• Related. Conformance reference.

Entry: a font is not embedded under PDF/A

• Symptom. A PDF/A build fails at font validation, or an external validator reports a non-embedded font.
• Likely cause. A glyph was drawn with a font whose program is not embedded. The PDF/A manager contract states that every font must be embedded and that no standard-14 font is permitted without embedding.
• Evidence / diagnosis. src/Contracts/PdfAManagerInterface.php declares validateFont(string $fontName, bool $isEmbedded, array $cmapForward) and documents the rule: every font must be embedded, and no standard 14 font is allowed without embedding. Concrete enforcement ships in nextpdf/pro.
• Resolution.
  1. Identify the font reported as not embedded.
  2. Configure that font with an embeddable program file, rather than relying on a built-in standard-14 face.
  3. For the Base 14 substitution interaction, read the fonts-and-tagging entry.
  4. Run the build again and re-validate.
• Related. Fonts and tagging.

Entry: JavaScript is present and PDF/A validation fails

• Symptom. A PDF/A build fails at JavaScript validation, or an external validator reports a JavaScript action.
• Likely cause. The document or a form field carries a JavaScript action. The PDF/A manager contract cites ISO 19005-4:2020 §6.7.1, which forbids JavaScript actions.
• Evidence / diagnosis. PdfAManagerInterface::validateNoJavaScript() and validateNoJavaScriptActions() both cite §6.7.1 in their docblocks.
• Resolution.
  1. Remove the JavaScript action from the document or form field.
  2. If the action is required for behavior, the document cannot be PDF/A. Produce a non-PDF/A variant for that use.
  3. Run the build again and re-validate.
• Related. Conformance reference.

Entry: tagged output does not advertise PDF/UA-2

• Symptom. A document built with tagging enabled is not recognized as PDF/UA-2, or its PDF/UA-2 claim is absent.
• Likely cause. The structure tree is empty. The engine does not advertise PDF/UA-2 for a document with no tagged structure, because an empty structure tree does not satisfy the profile.
• Evidence / diagnosis. The failure-path test tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php asserts that an empty tagged document does not advertise PDF/UA-2. This is documented engine behavior, not a defect.
• Resolution.
  1. Confirm that content is emitted through the tagging path, so the structure tree is populated instead of empty.
  2. Verify that the marked-content sequences map to structure elements.
  3. Run the build again and re-check the PDF/UA-2 status.
• Related. Fonts and tagging.

Entry: PDF/UA-2 fails on a missing or invalid language

• Symptom. A PDF/UA-2 check fails because a language entry is missing or is not a valid tag.
• Likely cause. The document or a structure element lacks a valid language. PDF/UA-2 requires a natural-language declaration; a missing or malformed Lang value fails the strict check.
• Evidence / diagnosis. The failure-path test tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php exercises the strict language requirement. Language tags are validated through src/Accessibility/Bcp47Validator.php; an invalid tag raises src/Accessibility/InvalidBcp47TagException.php.
• Resolution.
  1. Set a document-level language as a valid Best Current Practice (BCP) 47 tag, for example, en-US or zh-Hant-TW.
  2. Where a passage is in a different language, set the language on that structure element.
  3. Run the build again and re-validate.
• Related. Fonts and tagging.

Edge cases & gotchas

• The PDF/A and PDF/UA refusals described here are produced inside the engine. They are independent of an external validator’s verdict and do not replace it. Run a validator such as veraPDF for the authoritative result.
• The concrete PDF/A required-object writer (Extensible Metadata Platform (XMP) metadata stream, output intent with an International Color Consortium (ICC) profile) is resolved at runtime from nextpdf/pro. With only the core package installed, those objects are not emitted; a core-only build is not a complete PDF/A producer.
• The encryption refusal is absolute and order-independent; enabling PDF/A after the encryption call still raises the refusal.

See also

• Conformance reference
• Fonts and tagging
• Knowledge base index

Glossary: output intent · structure tree