Troubleshooting knowledge base

What this knowledge base covers

Use this knowledge base to map a failure you see to its cause and resolution. Each entry comes from the engine’s own exception classes, failure-path tests, and source guards, not speculation. If the engine has no code path for a given failure, this knowledge base does not invent one.

The knowledge base includes four topic pages:

• Signature validation — invalid signatures, incomplete chains, unknown revocation, and timestamp failures.
• PDF/A and PDF/UA validation — Portable Document Format/Archive (PDF/A) and Portable Document Format/Universal Accessibility (PDF/UA) issues, including missing output intent, untagged content, missing language, and embedded-font failures.
• Fonts and tagging — font not found, subsetting, CJK coverage, and structure-tree problems.
• Encryption and permissions — decryption failures and the permission-flag boundary.

How to read an entry

Each entry has five parts:

1. Symptom — what you see: an exception class, a message fragment, or a downstream validator verdict.
2. Likely cause — the input or configuration condition that the engine reports.
3. Evidence / diagnosis — how to confirm the cause. This part names the exact exception class, getContext() field, or test that demonstrates the behavior, so you can verify it rather than guess.
4. Resolution — the ordered steps to remove the cause.
5. Related — the module reference page or sibling entry to read next.

Identify a failure by exception type

NextPDF identifies an error by its PHP class, not by a string error code. No NPDF-#### constant exists in the exception classes. Catch the leaf exception when you need a targeted response, and read ContextAwareExceptionInterface::getContext() for structured diagnostic fields. Use NextPDF\Exception\NextPdfException as the base type; security failures also use NextPDF\Security\Exception\SecurityException.

For the full hierarchy and catch-order rules, read the exception reference.

<?php

declare(strict_types=1);

use NextPDF\Exception\NextPdfException;
use NextPDF\Contracts\ContextAwareExceptionInterface;

try {
    // ... engine call ...
} catch (NextPdfException $e) {
    $context = $e instanceof ContextAwareExceptionInterface
        ? $e->getContext()
        : [];
    \error_log($e->getMessage());
    // $context carries snake_case primitive fields safe to serialize.
}

Scope and boundary

This knowledge base covers how the engine detects and reports failures. It does not cover conformance verdicts from external validators, such as veraPDF or callas; those tools apply their own rule sets. When the engine refuses an operation to keep a document within a profile, such as refusing encryption under PDF/A, the relevant entry cites the governing clause and the exception that enforces it.

See also

• Exception reference — full hierarchy, catch order, and getContext() contract
• Conformance reference — PDF/A, PDF/UA, and PDF/X profile checkers

Glossary: context-aware exception