Core- und allgemeine Fehler

Geltungsbereich

Diese Einträge decken die Core- und allzweck-Exceptions ab, die NextPDF auslöst. Die meisten erweitern die Basis NextPdfException, die selbst \RuntimeException erweitert und ContextAwareExceptionInterface implementiert. Diese Schnittstelle stellt eine Methode bereit, getContext(): array, die eine flache snake_case-Map aus Primitiven zurückgibt, die sicher in eine Log- oder APM-Payload serialisiert werden kann.

Fangen Sie die NextPdfException-Familie mit einem einzigen catch (NextPdfException $e) ab. Fügen Sie zusätzlich ein catch (\RuntimeException $e) hinzu, um die wenigen Low-Level-Fehler in diesem Satz abzudecken, die \RuntimeException direkt erweitern (unten aufgeführt). Die Basis NextPdfException::getContext() gibt ein leeres Array zurück; Unterklassen überschreiben es, um Domänenfelder hinzuzufügen. Wo eine Klasse getContext() nicht überschreibt, erbt sie das leere Array, und das Diagnosedetail liegt stattdessen in der Meldung und den typisierten Gettern.

Vier Typen in diesem Satz erweitern nicht NextPdfException: BlackPointCompensationUnsupportedException und UnsupportedSourceDocumentException erweitern \RuntimeException direkt (fangen Sie sie als \RuntimeException ab), und ComplianceViolation und RuleViolation sind Value Objects, keine Exceptions — sie sind hier dokumentiert, weil sie die Fehler- und Verletzungsdaten modellieren, die die Engine zurückgibt.

Basis-Exception

NextPdfException

• Was es ist. abstract-Basis für die zentrale NextPDF-Exception-Familie über Core und seine Erweiterungspakete hinweg. Es erweitert \RuntimeException und implementiert ContextAwareExceptionInterface. Das Abfangen dieses einen Typs fängt die NextPdfException-Familie ab; die wenigen Fehler, die \RuntimeException direkt erweitern (oben aufgeführt), benötigen zusätzlich ein \RuntimeException-catch.
• Kontext. Die Basis getContext() gibt ein leeres Array zurück. Unterklassen überschreiben es, um domänenspezifische Felder zurückzugeben.
• Behebung. Wird nicht direkt ausgelöst. Verwenden Sie es als Catch-all-Typ; verzweigen Sie auf die konkrete Unterklasse für spezifische Behandlung.

Konfiguration und Feature-Gating

InvalidConfigException

• Wann sie ausgelöst wird. Wenn ein Config-Wert oder eine Kombination von Werten ungültig ist — eine fehlende Pflichteinstellung, eine sich gegenseitig ausschließende Option oder ein Wert außerhalb seines zulässigen Bereichs. Dies signalisiert einen Entwicklerfehler: Der aufrufende Code hat eine Konfiguration übergeben, die vor einem erneuten Versuch korrigiert werden muss. Die Meldung nennt den Schlüssel, den erwarteten Typ oder Bereich sowie den tatsächlichen Debug-Typ des übergebenen Werts.
• Kontext. getContext() gibt config_key, given_value und expected_type zurück. Typisierte Getter: getConfigKey(), getGivenValue(), getExpectedType().
• Behebung. Entwicklermaßnahme: Korrigieren Sie den benannten Konfigurationsschlüssel auf einen Wert des erwarteten Typs oder Bereichs, bevor Sie NextPDF erneut aufrufen.

NotImplementedException

• Wann sie ausgelöst wird. Wenn ein öffentlicher API-Einstiegspunkt erreicht wird, seine Implementierung in der aktuellen Version aber absichtlich fehlt. Wird für veraltete Shims verwendet, die existieren, um Pre-Bisect-Aufrufern einen lauten, umsetzbaren Fehler statt eines stillen No-op zu liefern. Die Meldung kombiniert ein maschinell durchsuchbares feature-Label und eine followUp-Referenz (Defect-ID, Tracking-Anker oder Sprint-Name).
• Kontext. Überschreibt getContext() nicht, gibt also ein leeres Array zurück. Die Werte $feature und $followUp sind öffentliche readonly-Eigenschaften und sind in die Meldung eingebettet.
• Behebung. Maßnahme des Bibliotheksaufrufers: Entfernen Sie den Aufruf, oder pinnen Sie auf eine künftige Version, die den benannten Follow-up bringt.

IncompatibleFeatureFlagsException

• Wann sie ausgelöst wird. Zur Config-Build-Zeit (Config::validate()), wenn eine CssFeatureFlags-Kombination intern inkonsistent ist — ein Flag setzt ein anderes voraus, das deaktiviert ist. Die einzige heute verbotene Kombination ist layoutSubgrid = true mit layoutGrid = false: Eine als Subgrid ausgelegte Achse leitet ihre Gitterlinien von einem übergeordneten Grid-Container ab (CSS Grid Layout Module Level 2 §1), sodass Subgrid ohne Grid ein Gitter beschreibt, das nicht existieren kann. Die Prüfung läuft gegen aufgelöste Flags, sodass CssRenderingMode::Safe (das jedes Phase-4+-Feature ausschaltet) die Kombination maskiert, statt sie auszulösen. Erweitert StrictModeViolation.
• Kontext. getContext() führt die übergeordneten Strict-Modus-Felder (cssDeviation, excId, chunkSha256, location) mit den Booleans layoutGrid und layoutSubgrid zusammen. Das location ist Config::validate(), und cssDeviation kodiert das Flag-Paar.
• Behebung. Maßnahme des Bibliotheksaufrufers: Aktivieren Sie layoutGrid zusammen mit layoutSubgrid, oder deaktivieren Sie layoutSubgrid.

IncompatibleRenderingModeException

• Wann sie ausgelöst wird. Zur Config-Build-Zeit, wenn eine Paarung aus CssRenderingMode und CssLayoutMode außerhalb der kompatiblen Zellen der Modus-Matrix fällt. Die einzige heute verbotene Paarung ist CssRenderingMode::Safe + CssLayoutMode::Retained — Safe schaltet jedes Phase-4+-Feature aus und lässt damit Retained-Mode-Formatierungskontexte (Grid, Subgrid, @container) ohne Konsumenten zurück, sodass die Kombination abgelehnt statt stillschweigend herabgestuft wird. Erweitert StrictModeViolation.
• Kontext. getContext() führt die übergeordneten Strict-Modus-Felder mit mode1 (dem Rendering-Modus-Wert) und mode2 (dem Layout-Modus-Wert) zusammen. Das cssDeviation kodiert das Modus-Paar; location ist Config::validate().
• Behebung. Maßnahme des Bibliotheksaufrufers: Wählen Sie Safe + Streaming für ein Rollback, oder einen Nicht-Safe-Rendering-Modus (Normal / Strict / Audit) mit Retained für Grid / Subgrid / Container Queries.

StrictModeViolation

• Wann sie ausgelöst wird. abstract-Basis für jede Spezifikationsabweichungs-Exception, die unter CssRenderingMode::Strict ausgelöst wird. Im Strict-Modus löst jede erkannte CSS-Abweichung, die nicht mit einem registrierten EXC-NNN-Exception-Eintrag verknüpft ist, am Erkennungspunkt eine Instanz dieser Klasse (oder einer Unterklasse) aus. Wird nicht direkt ausgelöst; siehe IncompatibleFeatureFlagsException und IncompatibleRenderingModeException.
• Kontext. getContext() gibt die vier ADR-023-Felder zurück: cssDeviation (Kurzlabel für das abweichende Konstrukt), excId (Registry-Bezeichner, wenn registriert, sonst null), chunkSha256 (Chunk-Hash der Spezifikationszitierung, wenn bekannt, sonst null) und location (für den Aufrufer lesbarer Ursprung, sonst null).
• Behebung. Maßnahme des Bibliotheksaufrufers: Registrieren Sie die Abweichung als neuen freigegebenen EXC-NNN-Eintrag, oder korrigieren Sie den Renderer, um die Abweichung zu entfernen.

HTML- und CSS-Eingabe

HtmlParsingException

• Wann sie ausgelöst wird. Wenn das Parsen der HTML-Eingabe oder die DOM-Konstruktion fehlschlägt: ungültige Charset-Deklarationen, Verletzungen des Eingabegrößenlimits, übermäßige Verschachtelungstiefe, Element-Count-Überläufe und Tabellenstrukturfehler wie ein Zeilenanzahl-Maximum. CSS-spezifische Ressourcenerschöpfung wird stattdessen von CssParserLimitExceededException und CssResolutionBudgetExceededException gemeldet.
• Kontext. getContext() gibt html_snippet (einen kurzen, gekürzten Auszug des fehlerverursachenden HTML), position (Byte-Offset, oder -1, wenn unbekannt) und rule (die verletzte Parser-Beschränkung) zurück. Typisierte Getter: getHtmlSnippet(), getPosition(), getRule().
• Behebung. Entwicklermaßnahme: Vereinfachen Sie die HTML-Eingabe oder passen Sie die Parser-Limits an.

CssParserLimitExceededException

• Wann sie ausgelöst wird. Wenn die CSS-Eingabe ein konfiguriertes Parser-Sicherheitslimit überschreitet. Zwei Kategorien werden über die benannten Konstruktoren abgedeckt: forByteLimit() (Stylesheet zu groß für sichere Regex-Verarbeitung) und forNestingDepth() (CSS-Verschachtelungsrekursion zu tief). Beide Meldungen nennen den tatsächlichen Wert und das Limit.
• Kontext. getContext() gibt limit_type (byte oder nesting_depth), actual und limit zurück.
• Behebung. Entwicklermaßnahme: Teilen Sie das Stylesheet in kleinere Sheets auf, oder reduzieren Sie die Verschachtelungstiefe, oder erhöhen Sie das konfigurierte Limit.

CssResolutionBudgetExceededException

• Wann sie ausgelöst wird. Wenn die CSS-:has()-Auflösung ihr Traversal-Budget überschreitet. Der zweistufige :has()-Resolver erzwingt ein striktes Node-Visit-Budget, um zu verhindern, dass pathologische Selektoren quadratische Dokumentdurchläufe verursachen; sobald die Gesamtbesuchszahl das Limit überschreitet, wird das Stylesheet als zu komplex abgelehnt. Die Meldung nennt die Besuchszahl und das Budget.
• Kontext. getContext() gibt visits und budget zurück. Typisierte Getter: getVisits(), getBudget().
• Behebung. Entwicklermaßnahme: Reduzieren Sie die Selektorkomplexität, oder erhöhen Sie das konfigurierte Budget.

Schriften und Bilder

FontNotFoundException

• Wann sie ausgelöst wird. Wenn eine Schriftdatei auf Dateisystemebene nicht gefunden oder gelesen werden kann: Die angeforderte Familie oder der Pfad existiert nicht, ist nicht lesbar, oder das konfigurierte Schriftenverzeichnis ist nicht zugänglich. Die Schriftdaten können gültig sein — dies signalisiert nur, dass sie nicht erreicht werden können. Die Meldung listet die durchsuchten Pfade auf.
• Kontext. getContext() gibt font_name, search_paths (eine Liste) und fallback_attempted (ein Bool) zurück. Typisierte Getter: getFontName(), getSearchPaths(), wasFallbackAttempted().
• Behebung. Entwicklermaßnahme: Prüfen Sie den Schriftpfad. Infrastrukturmaßnahme: Korrigieren Sie die Dateiberechtigungen für die Schriftdatei oder das Verzeichnis.

FontParsingException

• Wann sie ausgelöst wird. Wenn eine Schriftdatei gefunden wird, ihr Inhalt aber nicht nutzbar ist: Sie ist beschädigt, in einem nicht unterstützten Format oder es fehlen erforderliche Tabellen. Deckt strukturelle Validierungsfehler beim TrueType-, Type-1-, CFF- und OpenType-Parsen ab — abgeschnittene Header, ungültige Tabellenverzeichnisse, fehlende Pflichttabellen (head, hhea, OS/2), Entpackfehler und Größen- verletzungen. Die Meldung nennt die Datei und den Parse-Fehler.
• Kontext. getContext() gibt font_file und parse_error zurück. Typisierte Getter: getFontFile(), getParseError().
• Behebung. Entwicklermaßnahme: Ersetzen Sie die Schriftdatei durch eine gültige.

ImageProcessingException

• Wann sie ausgelöst wird. Wenn ein Bild nicht dekodiert werden kann, in einem nicht unterstützten Format vorliegt oder die GD/Imagick-Verarbeitung fehlschlägt: unkenntliche Magic Bytes, beschädigte JPEG-Daten, nicht unterstützte MIME-Typen, Verletzungen des Dateigrößenlimits und GD-Ressourcen- zuteilungsfehler. Das Bild war zugänglich, aber seine Pixeldaten konnten nicht zum Einbetten extrahiert werden.
• Kontext. getContext() gibt image_path (leer bei Inline-Daten), format (erkannt oder erwartet, z. B. jpeg, png, unknown) und operation (z. B. decode, resize, embed) zurück. Typisierte Getter: getImagePath(), getFormat(), getOperation().
• Behebung. Entwicklermaßnahme: Liefern Sie eine gültige, unterstützte Bilddatei.

Ausgabe, Layout und Serialisierung

CompressionException

• Wann sie ausgelöst wird. Wenn die FlateDecode-(zlib-)Komprimierung oder -Dekomprimierung fehlschlägt — gzcompress/gzuncompress-Fehler bei Content-Streams, Schriftdaten, Seiteninhalt, Anhangsdaten und Cross-Reference-Streams. Typischerweise ein beschädigter Eingabestream, unzureichender Speicher oder eine fehlende zlib-Erweiterung.
• Kontext. getContext() gibt algorithm (Filtername, z. B. FlateDecode, LZWDecode) und stream_length (Byte-Länge, oder -1, wenn unbekannt) zurück. Typisierte Getter: getAlgorithm(), getStreamLength().
• Behebung. Infrastrukturmaßnahme: Stellen Sie sicher, dass ext-zlib geladen und der Speicher ausreichend ist.

WriterException

• Wann sie ausgelöst wird. Wenn die PDF-Serialisierung, Linearisierung oder I/O-Ausgabe fehlschlägt: PdfWriter-Stream-Schreibfehler, Korruption der Cross-Reference-Tabelle, Header-/Trailer-Generierungsfehler, Fehler beim Auflösen von Objektreferenzen, Datei- schreibfehler und Ausgabepuffer-Überläufe. Ein gültiges In-Memory-Dokument konnte nicht in einen gültigen Byte-Stream serialisiert werden. Die Meldung nennt die Stufe.
• Kontext. getContext() gibt output_path (leer bei String-Ausgabe) und writer_state (die Stufe, z. B. header, body, xref, trailer) zurück. Typisierte Getter: getOutputPath(), getWriterState().
• Behebung. Infrastrukturmaßnahme: Prüfen Sie Speicherplatz, Dateiberechtigungen und den Ausgabestream.

PageLayoutException

• Wann sie ausgelöst wird. Wenn Seitenlayout-Beschränkungen nicht erfüllt werden können: Spaltenlayout-Verletzungen (unzureichende Breite, ungültige Spaltenzahl), Inhalts- überlauf über die Seitengrenzen hinaus und Randkonflikte. Das angeforderte Layout ist für die gegebenen Seitenabmessungen und den Inhalt geometrisch unmöglich. Die Meldung nennt die Seitennummer, wenn bekannt, und die verletzte Beschränkung.
• Kontext. getContext() gibt page_number (einsbasiert, oder 0, wenn unbekannt) und constraint zurück. Typisierte Getter: getPageNumber(), getConstraint().
• Behebung. Entwicklermaßnahme: Passen Sie Seitengröße, Ränder, Spalteneinstellungen oder Inhalt an.

TemplateException

• Wann sie ausgelöst wird. Wenn ein PDF-Template-Import oder eine Wiederverwendung im TemplateManager fehlschlägt: ungültige Template-Zustandsübergänge (Beginnen oder Beenden von Templates außerhalb der Reihenfolge), Verweis auf ein nicht existierendes Template und Stream- Komprimierungsfehler bei der Template-Serialisierung. Die Meldung nennt die Operation und die Template-ID, sofern zugewiesen.
• Kontext. getContext() gibt template_id (leer, wenn noch nicht zugewiesen) und operation (z. B. begin, end, use, serialize) zurück. Typisierte Getter: getTemplateId(), getOperation().
• Behebung. Entwicklermaßnahme: Korrigieren Sie die Reihenfolge der Template-Nutzung oder das Quell-PDF.

Content-Stream-Invarianten

ContentStreamBalanceException

• Wann sie ausgelöst wird. Wenn ein ContentStreamBuilder ein unausgewogenes Operatorpaar beim Stream-Schließen (oder mitten im Stream, wenn Invarianten eager geprüft werden) erkennt. Es erfasst die Tiefenzähler, die die Ausgleichsinvariante verletzt haben, sodass das Logging identifizieren kann, welcher Emitter ein q, BT oder BMC ohne sein passendes Q, ET oder EMC durchsickern ließ. Gemäß ISO 32000-2:2020 §8.4.2 (Grafikzustands- Stack), §9.4.1 (Textobjekte) und §14.6 (Marked Content).
• Kontext. getContext() gibt graphics_depth, text_block_depth, marked_content_depth und offending_operator zurück. Typisierte Getter: getGraphicsDepth(), getTextBlockDepth(), getMarkedContentDepth(), getOffendingOperator().
• Behebung. Entwicklermaßnahme: Lokalisieren Sie den Emitter, der ein Konstrukt geöffnet hat, ohne es zu schließen.

GraphicsStateBalanceException

• Wann sie ausgelöst wird. Wenn ein PDF-Content-Stream mit unausgewogenen q/Q- Operatoren schließt. ISO 32000-2:2020 §8.4.2 verlangt, dass jedes Grafikzustands-Save (q) durch genau ein Restore (Q) vor dem Stream-Ende ausgeglichen wird; eine Unwucht lässt Transformation, Clipping-Pfad, Farben und Rendering Intent in nachfolgende Seiten oder Form-XObjects durchsickern. Wird nur ausgelöst, wenn die strikte Grafikzustands- Prüfung aktiviert ist (NEXTPDF_GFXSTATE_STRICT=1); im entspannten Modus wird stattdessen eine Warnung über trigger_error() ausgegeben.
• Kontext. getContext() gibt save_depth zurück (positiv bei zu vielen Saves, negativ bei zu vielen Restores). Typisierter Getter: getSaveDepth().
• Behebung. Entwicklermaßnahme: Lokalisieren Sie das nicht ausgeglichene save()/restore()- Paar.

MissingShadingResourceException

• Wann sie ausgelöst wird. Wenn ConicGradientRenderer::render() ohne einen Shading-Resource-Registry-Kontext aufgerufen wird. Die Breaking Change in v10.0.0 entfernte den vorherigen impliziten Marker-Map-Surrogatpfad: Aufrufer müssen den Renderer mit einem ShadingResourceRegistryInterface konstruieren, damit das /ShadingType 4- indirekte Objekt gegen das Shading-Resource-Subdictionary der Seite registriert wird (ISO 32000-2 §8.7.4.2 / §8.7.4.3). Die Meldung nennt den Aufrufer- kontext und verweist auf den Migrationshinweis v9.x→v10.0.
• Kontext. getContext() gibt context (ein kurzes Aufrufer-Kontext-Label, z. B. ConicGradientRenderer::render) zurück.
• Behebung. Maßnahme des Bibliotheksaufrufers: Binden Sie eine Shading-Resource-Registry-Instanz in den Renderer-Konstruktor ein, bevor Sie render() aufrufen.

Linearisierung (Fast Web View)

LinearizationInvariantException

• Wann sie ausgelöst wird. Wenn der dreistufige v2-Linearizer erkennt, dass seine MEASURE → PLACE → FILL-Zusicherungen verletzt wurden: eine Pass-3-Byte-Zahl, die nicht mit der in Pass 1 vorhergesagten Dateilänge übereinstimmt (Offset-Drift), ein Linearisierungs- Dictionary-Platzhalter, der für die serialisierte Breite zu klein ist, oder ein /H [offset length]-Hint-Stream-Offset, der nicht mit der endgültigen Ausgabe übereinstimmt. Dies zutage zu fördern statt ein kaputtes PDF auszugeben, ist eine erklärte Sicherheitsgarantie.
• Kontext. getContext() gibt invariant (den Namen der verletzten Invariante), expected, actual und delta (die vorzeichenbehaftete Differenz) zurück. Typisierte Getter: getInvariant(), getExpectedValue(), getActualValue().
• Behebung. Maintainer-Maßnahme: Reichen Sie einen Fehlerbericht ein — diese Invarianten sollten für alle wohlgeformten Eingaben gelten. Erfassen Sie die verkettete vorherige Exception.

LinearizationUnimplementedException

• Wann sie ausgelöst wird. Wenn das Linearizer-Feature-Flag auf ein Backend gesetzt ist, das absichtlich deaktiviert ist. Derzeit nur ausgelöst für linearizerVersion === 'v1-noop', die Notfall-Downgrade-Einstellung, die alle Linearisierungsversuche zur Laufzeit ohne Codeänderung oder Redeploy ablehnt — nützlich, um Fast Web View in der Produktion per Kill-Switch zu deaktivieren.
• Kontext. getContext() gibt reason (eine kurze, menschenlesbare Erklärung) zurück. Typisierter Getter: getReason().
• Behebung. Maßnahme von Betrieb / Release-Engineering: Passen Sie die Konfiguration an oder aktualisieren Sie auf eine korrigierte Backend-Version.

Konformitäts- und Profil-Invarianten

ConformanceViolationException

• Wann sie ausgelöst wird. Wenn ein angefordertes Feature nicht ausgegeben werden kann, ohne den deklarierten ISO-Konformitätsvertrag des Dokuments zu brechen, und die Engine fail-closed reagiert, statt ein nicht konformes Objekt zu schreiben. Der kanonische Auslöser ist eine Multimedia-Screen-Annotation oder Rendition-Action (ISO 32000-2:2020 §12.5.6.18 / §13.2) unter einem PDF/A-Archivprofil, was jeder PDF/A-Teil verbietet (ISO-19005-Serie) — die Datei würde die veraPDF-Validierung nicht bestehen, daher verweigert die Engine dies vorab.
• Kontext. getContext() gibt conformance_mode (den deklarierten Modus, z. B. pdfa4) und feature (das abgelehnte Feature, z. B. Screen annotation) zurück. Beide sind öffentliche readonly-Eigenschaften. Der Grund ist die Exception-Meldung.
• Behebung. Entwicklermaßnahme: Lassen Sie den Multimedia-Aufruf für Archivausgaben weg, oder zielen Sie auf ein Nicht-Archiv-Konformitätsprofil (Standard ConformanceMode::Plain).

PdfRViolationException

• Wann sie ausgelöst wird. Wenn eine PDF/R-1-(ISO 23504-1:2020-)Konformitätsinvariante verletzt wird, entweder bei der Value-Object-Konstruktion (die Profile PdfRStrip, PdfRPage, PdfRDocument) oder zur Validator-Zeit (PdfRValidator). Es erfasst die betreffende normative Klausel und eine einzeilige Verletzungsbeschreibung, damit Audit- Konsumenten Befunde an die korrekte §6-Unterklausel routen können, ohne Freitext zu parsen.
• Kontext. getContext() gibt standard (immer ISO 23504-1:2020), clause (der Klauselpfad, z. B. 6.6.1) und violation zurück. Typisierte Getter: getClause(), getViolation().
• Behebung. Entwicklermaßnahme: Korrigieren Sie die abgelehnte Eingabe oder bauen Sie das Dokument neu auf, damit es der zitierten Klausel entspricht.

Barcode-Erzeugung

BarcodeException

• Wann sie ausgelöst wird. Wenn die Barcode-Erzeugung aufgrund ungültiger Daten oder Kodierungsfehler über alle unterstützten Symbologien hinweg fehlschlägt (Code 39/128, UPC-A/E, EAN-8/13, Interleaved/Standard 2-of-5, POSTNET, PLANET, MSI, ISBN, ISSN, QR Code, PDF417, DataMatrix, JabCode) sowie bei GD-Rendering-Fehlern während der Bild- erstellung. Der Barcode-Wert wird in Meldung und Kontext auf 128 Byte gekappt — überlange oder binäre Payloads werden gekürzt mit einem ... (<N> bytes, truncated)-Marker gespeichert, sodass sie nicht im Ganzen in ein Log kopiert werden können.
• Kontext. getContext() gibt barcode_type (Symbologie, z. B. QRCODE, EAN13, CODE128) und value (den gekürzten Wert) zurück. Typisierte Getter: getBarcodeType(), getValue().
• Behebung. Entwicklermaßnahme: Korrigieren Sie die Barcode-Daten oder die Symbologie- auswahl.

BarcodeEncoderNotFoundException

• Wann sie ausgelöst wird. Aus BarcodeEncoderRegistry, wenn der angeforderte Encoder- Typ unbekannt ist oder sein Capability-Gate geschlossen ist. Es implementiert außerdem PSR-11 Psr\Container\NotFoundExceptionInterface, sodass die Registry ein standardkonformer Container ist. Die Meldung nennt die Symbologie und den Grund.
• Kontext. Überschreibt getContext() nicht, gibt also ein leeres Array zurück. Der type und der reason sind über die Getter getType() und getReason() sowie in der Meldung verfügbar.
• Behebung. Entwicklermaßnahme: Registrieren Sie den Encoder, oder installieren Sie das Paket, das ihn bereitstellt (zum Beispiel nextpdf/pro für Micro QR / DotCode / HanXin / JabCode).

Kryptografie, Verschlüsselung und Signaturen

EncryptionException

• Wann sie ausgelöst wird. Wenn die PDF-Verschlüsselung oder -Entschlüsselung fehlschlägt: AES-256-CBC- Ver-/Entschlüsselungsfehler, OpenSSL-Fehler, ungültige IV-Größen, Hash-Berechnungs- fehler und UE/OE-Wertberechnungsfehler. Typischerweise eine fehlende oder falsch konfigurierte OpenSSL-Erweiterung, ungültiges Schlüsselmaterial oder beschädigte verschlüsselte Daten. Die Meldung nennt die Operation und den Algorithmus.
• Kontext. getContext() gibt algorithm (z. B. AES-256-CBC) und operation (z. B. encrypt, decrypt, key_derivation) zurück. Typisierte Getter: getAlgorithm(), getOperation().
• Behebung. Infrastrukturmaßnahme: Stellen Sie sicher, dass OpenSSL verfügbar und korrekt konfiguriert ist. Siehe Verschlüsselung und Berechtigungen.

UnsupportedAlgorithmException

• Wann sie ausgelöst wird. Wenn ein kryptografischer Algorithmus in der aktuellen Laufzeitumgebung nicht ausgeführt werden kann: Eine erforderliche PHP-Erweiterung ist nicht verfügbar, der zugrunde liegenden Bibliothek fehlt das Primitive, die mitgelieferte hash-Erweiterung kann keine SHAKE/XOF-Variante synthetisieren, oder der Algorithmus ist nicht in der SignatureAlgorithmRegistry registriert. Die Engine darf nicht stillschweigend auf ein schwächeres Primitive herabstufen, daher fördert sie dies stattdessen zutage. Die statische Factory nonFipsHostUnderFipsProfile() löst sie aus (mit dem Algorithmusbezeichner regulatory-profile:fips), wenn RegulatoryProfile::FIPS gewählt wurde, aber ein FIPS-validierter OpenSSL-Provider nicht bestätigt werden kann (sowohl FIPS_ABSENT als auch INDETERMINATE reagieren fail-closed).
• Kontext. getContext() gibt algorithm (Name oder OID, z. B. shake256, Ed25519, AES-256-GCM) und reason (für den Betrieb umsetzbar) zurück. Typisierte Getter: getAlgorithm(), getReason().
• Behebung. Betriebsmaßnahme: Installieren Sie die fehlende Erweiterung oder aktualisieren Sie die Laufzeitumgebung; für das FIPS-Gate installieren Sie einen FIPS-validierten OpenSSL-Build oder setzen Sie NEXTPDF_FIPS_MODE explizit. Entwicklermaßnahme: Registrieren Sie einen benutzerdefinierten Algorithmus- Deskriptor über SignatureAlgorithmRegistry::register().

SignatureException

• Wann sie ausgelöst wird. Wenn eine digitale Signaturoperation fehlschlägt: Zertifikats- und Privatschlüssel-Handhabung (PKCS#12-Parsing, PEM/DER-Dekodierung, X.509- Validierung), PKCS#7/CMS-Konstruktion, ECDSA-Signaturformat, Container-Größen- verletzungen, DER-Kodierung und PAdES-Orchestrierung. TSA-spezifische Fehler werden stattdessen vom spezifischeren TsaException gemeldet. Bevorzugen Sie die typisierten benannten Factorys gegenüber dem positionellen Konstruktor; jede bindet die Grundursache an das Meldungsende. Beispiele: ltvCapabilityMissing() (B-LT/B-LTA benötigt nextpdf/enterprise), tsaRequired() / tsaUrlEmpty() / tsaEmptyToken(), httpClientMissing(), hsmSignerMissing() / hsmSignatureEmpty(), signatureContentsNotFound() / signatureContentsPaddingCorrupt(), unexpectedKeyType(), pemDecodingFailed(), die Ed25519-Familie (ed25519SignatureMalformed(), ed25519RoundTripVerifyFailed(), ed25519KeyParseFailed(), ed25519SeedInvalid(), ed25519SecretKeyMalformed(), ed25519PublicKeyInvalid()), documentTimestampNotEmitted(), algorithmPolicyRejected(), digestOnlyAlgorithmRefused(), encryptedLtvUnsupported(), incrementalUpdateWriterMissing() und das OCSP-Status-Paar nonSuccessfulOcspResponseStatus() / reservedOcspResponseStatus() (RFC 6960 §4.2.1). Diese Factorys reagieren fail-closed, statt eine stillschweigend herabgestufte Signatur auszugeben.
• Kontext. getContext() gibt cert_info (Subject-DN oder Thumbprint, oder leer), signature_level (die versuchte PAdES-Stufe, z. B. B-B, B-T, B-LT, B-LTA) und detail (die umsetzbare Diagnose, leer für den Legacy-positionellen Konstruktor) zurück. Typisierte Getter: getCertInfo(), getSignatureLevel(), getDetail().
• Behebung. Entwicklermaßnahme: Korrigieren Sie die Zertifikats-/Schlüsselkonfiguration. Für Capability-fehlende Factorys installieren Sie das benannte Paket. Siehe Signatur- und Zeitstempelfehler für Symptom-und-Lösung-Einträge pro Factory.

BlackPointCompensationUnsupportedException

• Wann sie ausgelöst wird. Aus NullBlackPointCompensationTransform::transform(), wenn ein Aufrufer den Null-Adapter bittet, eine Nicht-Default-ISO-18619- Schwarzpunktkompensation anzuwenden. Der Null-Adapter ist der sichere Fallback für Umgebungen ohne Farbmanagement-Backend; ein transformiertes Sample ohne ein echtes Farbmanagement-Modul zu erzeugen, würde die Konvertierung stillschweigend falsch melden. Anders als die meisten Einträge hier erweitert dies \RuntimeException direkt, nicht NextPdfException, sodass bestehende catch (\RuntimeException)-Pfade weiter funktionieren.
• Kontext. Kein getContext(); es ist eine einfache \RuntimeException. Das Detail steht in der Meldung.
• Behebung. Entwicklermaßnahme: Registrieren Sie eine echte BlackPointCompensationTransform (LittleCMS, Argyll, pure-PHP), oder beschränken Sie /UseBlackPtComp auf BlackPointCompensation::Default.

Dokumentzusammenstellung und Barrierefreiheit

UnsupportedSourceDocumentException

• Wann sie ausgelöst wird. Wenn ein Quelldokument nicht sicher in eine Merge-/Split-Ausgabe kopiert werden kann und die Operation fail-closed fehlschlägt, statt ein beschädigtes oder sicherheitskompromittiertes Ergebnis auszugeben. Verwenden Sie die benannten Factorys: encrypted() (ISO 32000-2 §7.6 — Inhalt kann ohne den Schlüssel nicht kopiert werden), signed() (§12.8 — das Kopieren von Seiten würde den Signatur-Byte-Bereich ungültig machen), unsupportedStreamFilter() (ein Filter, den der Objektgraph-Reader nicht Roundtrip-fähig verarbeiten kann), multipleInteractiveForms() (eine dokumentierte Einschränkung: mehr als eine Quelle trägt ein nicht leeres /AcroForm, §12.7) und splitWithInteractiveForm() (eine dokumentierte Einschränkung: das Teilseiten-Subsetting einer formulartragenden Quelle würde Widgets verwaisen lassen). Erweitert \RuntimeException direkt, nicht NextPdfException.
• Kontext. Kein getContext(); es ist eine einfache \RuntimeException. Die Ursache und die betroffene Objektnummer werden in der Meldung genannt.
• Behebung. Entwicklermaßnahme: Entschlüsseln Sie die Quelle zuerst oder liefern Sie den Schlüssel; bei signierten Quellen signieren Sie stattdessen nach dem Zusammenführen; bei Multi-Form-Merges flachen oder entfernen Sie die Formularfelder aller Quellen bis auf eine; bei formulartragenden Splits flachen Sie das Formular vor dem Aufteilen.

InvalidBcp47TagException

• Wann sie ausgelöst wird. Aus Bcp47Validator::validate(), wenn ein kandidierender Sprach-Tag unter RFC 5646 §2.1 ABNF fehlgeformt ist oder die kuratierte Registry-Suche nicht besteht. Domänenspezifisch für BCP-47 / ISO 14289-2:2024 §8.4.4, getrennt von InvalidConfigException, damit Aufrufer hinter der Barrierefreiheits-Naht einen schmalen Typ abfangen können. Das Prädikatpaar Bcp47Validator::isWellFormed() / isValid() bleibt die rückwärtskompatible Rückgabewert-Oberfläche für Aufrufer, die Verzweigung gegenüber Exceptions bevorzugen.
• Kontext. getContext() gibt tag (den Kandidaten exakt wie übergeben) und reason (einen stabilen, maschinenlesbaren Ablehnungscode, z. B. empty-string, well-formed-shape, unregistered-primary, duplicate-variant) zurück. Typisierte Getter: getTag(), getReason().
• Behebung. Entwicklermaßnahme: Korrigieren Sie den Sprach-Tag zu einem wohlgeformten, registrierten BCP-47-Tag. Siehe Schriften und Tagging.

FormFieldAccessibilityException

• Wann sie ausgelöst wird. Wenn ein interaktives Formularfeld sich auf einen synthetischen (nicht vom Autor bereitgestellten) barrierefreien Namen verlassen würde, während ein PDF/UA-Dokument mit aktivierter strikter Durchsetzung barrierefreier Feldnamen erzeugt wird. Standard-PDF/UA-Ausgaben geben einen synthetischen Fallback-Namen in das Widget-/Contents aus, sodass ein Feld nie unbenannt ist; der Strict-Modus verlangt stattdessen, dass der Autor einen aussagekräftigen Namen liefert (einen Tooltip, oder eine Beschriftung für eine aktionslose Push-Button), damit Screenreader-Nutzende eine echte Beschreibung erhalten (ISO 14289-2:2024 §8.10.2).
• Kontext. Überschreibt getContext() nicht, gibt also ein leeres Array zurück. Das $fieldId ist eine öffentliche readonly-Eigenschaft; der Grund ist die Meldung.
• Behebung. Entwicklermaßnahme: Liefern Sie einen Tooltip / barrierefreien Namen für das benannte Feld, bevor Sie ein striktes PDF/UA-Dokument erzeugen, oder deaktivieren Sie den Strict-Modus. Siehe PDF/A- und PDF/UA-Validierung.

VendorExtensionRegistryConflictException

• Wann sie ausgelöst wird. Aus VendorExtensionRegistry::register(), wenn ein Aufrufer ein bekanntes PDF-Developer-Extension-Vendor-Präfix (ISO 32000-2:2020 §7.12.1) mit einer Beschreibung erneut registriert, die den bereits registrierten Metadaten widerspricht. Deskriptoren sind append-only und konfliktgeprüft; die typisierte Exception ersetzte eine generische \RuntimeException, damit Aufrufer diese spezifische Klasse abfangen können.
• Kontext. getContext() gibt prefix, existing_description und attempted_description zurück. Typisierte Getter: getPrefix(), getExistingDescription(), getAttemptedDescription().
• Behebung. Entwicklermaßnahme: Registrieren Sie das Präfix mit der bestehenden Beschreibung, oder verwenden Sie ein eindeutiges Präfix; überschreiben Sie keine registrierten Metadaten.

Audit-Export

AuditExportException

• Wann sie ausgelöst wird. Wenn die Zusammenstellung des Audit-Export-Bundles, die Erzeugung der Traceability-Matrix oder die Schema-Projektion zur Laufzeit fehlschlägt. Deckt I/O gegen claims.json / manifest.json, JSON-Kodierung/Dekodierung des kanonischen Bundles und Schema-Versions-Mismatch auf dem AuditExporter::projectToV1()- Rückwärtskompatibilitätspfad ab. Die Meldung nennt die Stufe, das Artefakt, sofern bekannt, und das Detail.
• Kontext. getContext() gibt stage (z. B. read_claims, encode_bundle, project_v1), detail und artefact (Pfad oder schema_version, der den Fehler ausgelöst hat) zurück. Typisierte Getter: getStage(), getDetail(), getArtefact().
• Behebung. Maßnahme von Compliance / DevOps: Prüfen Sie die Eingabe-Artefaktpfade, erzeugen Sie claims.json aus einem sauberen Lauf neu, oder bauen Sie das Manifest neu, bevor Sie den Export erneut versuchen.

Violation-Value-Objects

Dies sind keine Exceptions. Es sind unveränderliche Value Objects, die die Engine zurückgibt, um eine einzelne Verletzung zu beschreiben; sie tragen kein getContext().

ComplianceViolation

• Was es ist. Ein final readonly Value Object, das einen Regelverstoß repräsentiert, der von einem externen Validator (veraPDF oder gleichwertig) gemeldet wird, einschließlich der ISO- Klauselreferenz und des Orts innerhalb der PDF-Struktur.
• Felder. Öffentliche readonly-Eigenschaften: ruleId (Validator-Regelbezeichner, z. B. 6.1.2-1), clause (ISO-Klauselreferenz, z. B. ISO 19005-1:2005, 6.1.2), severity (z. B. error, warning), location (Objektpfad innerhalb der PDF-Struktur) und message (menschenlesbare Beschreibung).
• Verwendung. Inspizieren Sie die von einem Compliance-Validator zurückgegebene Sammlung; routen oder zeigen Sie jeden Eintrag nach severity und clause an. Siehe PDF/A- und PDF/UA-Validierung.

RuleViolation

• Was es ist. Ein final readonly Value Object, das eine einzelne Schematron- / EN-16931-Geschäftsregelverletzung repräsentiert, zurückgegeben von SchematronRunnerInterface::runRules() und innerhalb von ValidationResult::$ruleViolations aggregiert. Stabilität ist experimental.
• Felder. Öffentliche readonly-Eigenschaften: ruleId (EN-16931-Bezeichner wie BR-{n}, BR-CO-{n}, BR-CL-{n}, BR-DEC-{n} oder ein stufenspezifisches Pack), severity (ein RuleSeverity-Enum), message (Regeltext, en-GB), xpath (XPath in das eingebettete XML, null für dokumentweite Regeln) und semanticPath (Punktnotations-BG/BT-Pfad wie BG-22.BT-106, null für strukturelle Verletzungen).
• Verwendung. Inspizieren Sie die Sammlung am Validierungsergebnis; routen oder zeigen Sie jeden Eintrag nach severity, ruleId und Locator an.

Siehe auch

• Index der Fehlerreferenz
• Index der Wissensdatenbank
• Signatur- und Zeitstempelfehler
• Verschlüsselung und Berechtigungen
• Schriften und Tagging
• PDF/A- und PDF/UA-Validierung