Error reference

This is the reference list of the exceptions NextPDF Core raises, organised by area. Each category page documents, per class, when it is thrown, the structured data it carries, and how to recover. If you are diagnosing a symptom rather than catching a specific class, start with the troubleshooting guides instead — they are organised by what you observe.

At a glance

Most exceptions extend a single base, NextPdfException, so you can catch the whole family with one catch block.
NextPdfException is context-aware: it implements ContextAwareExceptionInterface, which declares getContext(): array. Many subclasses override getContext() to return structured diagnostic keys; others inherit the empty default and expose their detail through the message and typed getters.
A small number of low-level exceptions extend PHP’s \RuntimeException directly rather than NextPdfException. These are not context-aware and carry their detail on public readonly properties. Each category page flags them explicitly.
Two compliance types named …Violation (ComplianceViolation, RuleViolation) are value objects, not exceptions — they describe a finding without being thrown.

The base type and the context contract

NextPdfException is an abstract class that extends \RuntimeException and implements ContextAwareExceptionInterface. The contract is small:

interface ContextAwareExceptionInterface
{
    /** @return array<string, mixed> structured, log-safe diagnostic context */
    public function getContext(): array;
}

A defensive handler therefore looks like this:

use NextPDF\Exception\NextPdfException;

try {
    // … NextPDF operation …
} catch (NextPdfException $e) {
    $logger->error($e->getMessage(), $e->getContext());
    // getContext() returns [] when a subclass does not override it;
    // the message and any typed getters still carry the detail.
}

Because some failures surface as a bare \RuntimeException (see the per-category notes), a belt-and-braces boundary may also catch \RuntimeException and inspect the concrete type.

Error reference

At a glance

The base type and the context contract

Categories

See also