Rendering- und I/O-Fehler

Geltungsbereich

Diese Einträge decken die Rendering- und Input/Output-(I/O-)Exceptions ab, die ausgelöst werden, während die HTML-Pipeline Inhalt layoutet, der Paged-Media-Resolver die Seiten- geometrie zuweist, der Text-Shaper komplexe Schriftsysteme verarbeitet, die Typografie-Stufe Zeilen umbricht, der Writer ein Dokument serialisiert, der Reader ein bestehendes PDF parst und die Metadaten-Stufe ein Extensible-Metadata-Platform-(XMP-)Paket liest.

Zwei Basishierarchien erscheinen unten, und der Unterschied bestimmt, welche Diagnose- daten Sie nach einem catch lesen können:

• NextPdfException implementiert ContextAwareExceptionInterface::getContext(): array. Die Basis- implementierung gibt ein leeres Array zurück; eine Unterklasse trägt strukturierte Schlüssel nur dann, wenn sie getContext() überschreibt. Unterklassen, die es nicht überschreiben, legen ihre Daten dennoch über public readonly-Eigenschaften offen.
• Mehrere Klassen hier erweitern PHPs RuntimeException direkt. Sie sind nicht kontextbewusst und haben keine getContext()-Methode; lesen Sie stattdessen ihr getMessage() und etwaige öffentliche Eigenschaften.

Jeder Eintrag nennt die exakte Klasse, die Auslösebedingung, die Kontextschlüssel oder öffentlichen Eigenschaften, die er trägt, und den Behebungspfad.

HTML-Layout und Paged Media

UnsplittableContentException

• Wann sie ausgelöst wird. Die HTML-Layout-Engine löst dies aus, wenn Inhalt, der mit break-inside: avoid markiert ist (eine Tabellenzelle, deren Umbruchbeschränkung Avoid ist), eine gemessene Höhe hat, die die nutzbare Höhe einer einzelnen Seite überschreitet. Die Engine kann nicht zugleich die Avoid-Break-Beschränkung und die Seitengrenze erfüllen, daher scheitert sie, statt stillschweigend überzulaufen.
• Getragene Daten. Erweitert NextPdfException, überschreibt aber nicht getContext(), sodass getContext() ein leeres Array zurückgibt. Die Diagnosedaten liegen auf public readonly-Eigenschaften: gridRow (int), gridCol (int), contentHeight (float, Punkte) und pageHeight (float, Punkte). Die Meldung nennt die Zellkoordinaten und beide Höhen.
• Behebung. Entfernen Sie die break-inside: avoid-Beschränkung an der betreffenden Zelle, reduzieren Sie den Inhalt der Zelle, sodass er auf eine Seite passt, oder vergrößern Sie die Seiten- größe oder verringern Sie ihre Ränder, sodass die nutzbare Höhe den Inhalt aufnimmt.

BudgetExceededException

• Wann sie ausgelöst wird. Retained-Mode-Layout-Primitive lösen dies aus, wenn eines der vier im Architecture-Decision-Record ADR-020 definierten Ressourcenbudget-Tiers verletzt wird und der Aufrufer sich für einen harten Fehler statt des weichen Fallbacks entschieden hat. Der Standardpfad löst nicht aus: ContainerLayout::acceptChild() gibt false zurück, der Aufrufer fällt auf Block-Layout zurück, und eine Warnung wird ausgegeben. Die Exception ist für Validierung zur Konfigurationszeit und für Tests reserviert, die das exakte Verletzungstupel prüfen. Die Tiers sind per-child (ein erfasster Kind-Stream überschreitet seine Kappung), per-container (das Tier-1- Node-Count-Budget), per-document (das Layout-Pass- oder Verschachtelungstiefen-Budget) und global (die SDK-weite 256-MB-Peak-Resident-Set-Size-Obergrenze).
• Getragene Daten. Überschreibt getContext(), das eine stabile Form mit acht Schlüsseln zurückgibt, die von Application-Performance-Monitoring-(APM-)Tooling konsumiert wird: budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize und processedItemCount. Die ersten vier Schlüssel sind die ursprüngliche v1.0.0-Teilmenge und sind stets befüllt; die letzten vier sind standardmäßig null oder 0, wenn der Konstruktor ohne sie aufgerufen wird. getCausalWarningCode() ordnet das (Tier, Container-Typ)-Tupel dem WarningCode zu, den der weiche Fallback-Pfad ausgegeben hätte.
• Behebung. Bei einer Konfigurationsverletzung senken Sie den angeforderten Wert wieder in die dokumentierte Hülle zurück (zum Beispiel akzeptiert das Retained-Node-Budget 5.000 bis 100.000 über Config::withRetainedNodeBudget()). Bei einer Inhaltsverletzung reduzieren Sie die Container-Verschachtelung oder die Node-Zahl, oder verlassen Sie sich auf den standardmäßigen weichen Fallback auf Block-Layout, statt sich für die Hard-Failure-Oberfläche zu entscheiden.

UnsupportedNamedPageException

• Wann sie ausgelöst wird. Die Paged-Media-Stufe löst dies fail-closed aus, wenn ein Dokument eine benannte @page <ident> { … }-Regel deklariert (über die page: <ident>-Eigenschaft an Inhalt gebunden). Benannte Seiten aus CSS Paged Media Level 3 §3.4 und Level 4 §3.2 — einschließlich der :first-, :left-, :right- und :blank- Pseudoklassen sowie benannter size:- und rotate:-Overrides — werden geparst, aber kein Produktions-Layout-Pfad konsumiert sie. Die Engine verweigert, statt die stillschweigend-falsche Standardpaginierung auszugeben, die das Verwerfen der Regel erzeugen würde.
• Getragene Daten. Überschreibt getContext(), das page_names (Liste der eindeutigen Idents, die den Fehler ausgelöst haben, in Quellreihenfolge), has_size_override (bool), has_rotate_override (bool) und has_pseudo_classes (bool) zurückgibt. Dieselben Werte werden auf den öffentlichen Eigenschaften pageNames, hasSizeOverride, hasRotateOverride und hasPseudoClasses offengelegt.
• Behebung. Entfernen Sie die benannten @page <ident>-Regeln und etwaige page: <ident>- Bindungen, und drücken Sie die beabsichtigte Geometrie über die unterstützte unbenannte @page { … }-Regel und ihre Pseudoklassenformen aus. Alternativ pinnen Sie auf eine künftige Version, die volle Named-Page-Layout-Unterstützung bringt.

Typografie und Text-Shaping

IcuRequirementException

• Wann sie ausgelöst wird. Die Textsegmentierung löst dies aus, wenn sie den International-Components-for-Unicode-(ICU-)Zeilenumbruch-Iterator benötigt, aber die Require-ICU-Policy aktiv ist (NEXTPDF_REQUIRE_ICU=1), während die ext-intl- Erweiterung und IntlBreakIterator nicht verfügbar sind.
• Getragene Daten. Erweitert RuntimeException direkt, ist also nicht kontextbewusst und hat kein getContext(). Es ist eine strikte Verfeinerung der generischen Exception, die derselbe Codepfad zuvor auslöste, sodass bestehende catch (\RuntimeException)-Handler weiter funktionieren.
• Behebung. Installieren und aktivieren Sie ext-intl, damit der ICU-Break-Iterator verfügbar ist, oder heben Sie NEXTPDF_REQUIRE_ICU auf, um auf den Nicht-ICU- Segmenter zurückzufallen, wo die Require-ICU-Policy nicht zwingend ist.

ScriptShaperException

• Wann sie ausgelöst wird. Dies ist die Basis-Exception für das Script-Shaping-Service- Provider-Interface (SPI). Sie wird heute nicht direkt ausgelöst; stattdessen werden konkrete Subtypen ausgelöst. Fangen Sie diesen Typ ab, um jeden Shaping-Fehler an einer Stelle zu behandeln.
• Getragene Daten. Erweitert RuntimeException direkt; nicht kontextbewusst, kein getContext().
• Behebung. Verzweigen Sie auf den konkreten Subtyp. Siehe NotYetImplementedException unten für den einzigen in der aktuellen Version ausgelieferten Subtyp.

NotYetImplementedException

• Wann sie ausgelöst wird. Jeder Platzhalter-Script-Shaper löst dies aus seinem shape()-Body aus für Schriftsysteme, deren konkretes Shaping zurückgestellt ist (Mongolisch und Tibetisch). Die Shaping-SPI-Naht ist architektonisch bereit, aber das echte Shaping steht noch aus, bis ein von Muttersprachlern validierter Fixture vorliegt. Eine Exception statt eines stillen No-op auszulösen, fördert versehentliche Produktionsverdrahtung zur Laufzeit zutage, statt ungeshapten Text in ein PDF auszugeben, das getaggte Barrierefreiheit beansprucht.
• Getragene Daten. Erweitert ScriptShaperException (und damit RuntimeException), ist also nicht kontextbewusst und hat kein getContext(). Die Diagnosedaten liegen auf ihren public readonly-Eigenschaften: bcp47LanguageTag (der BCP-47-Tag des Runs, wie mn-Mong oder bo-Tibt) und missingCapability (die konkrete Capability, die der Implementierung fehlt). Die Meldung enthält beide.
• Behebung. Routen Sie Runs in den nicht implementierten Schriftsystemen in der Produktion nicht durch den Shaper. Erkennen Sie den Sprach-Tag vorgelagert und fallen Sie entweder auf einen anderen Rendering-Pfad zurück oder pinnen Sie auf eine künftige Version, die Shaping für das betroffene Schriftsystem bringt.

Writer-Ausgabeprofile und Verschlüsselung

Pdf14FeatureRejectedException

• Wann sie ausgelöst wird. Der Writer löst dies aus, wenn ein Dokument ein unter dem PDF-1.4-Ausgabeprofil (ISO 19005-1:2005 / PDF/A-1) verbotenes Feature enthält, das in späteren PDF-Versionen eingeführte Konstrukte untersagt.
• Getragene Daten. Erweitert NextPdfException, überschreibt aber nicht getContext(), sodass getContext() ein leeres Array zurückgibt. Die Diagnosedaten liegen auf ihren public readonly-Eigenschaften: feature (der Name des abgelehnten Features), reason (warum es verboten ist) und isoClause (die ISO-Klauselreferenz). Die Meldung kombiniert alle drei.
• Behebung. Entfernen oder ersetzen Sie das abgelehnte Feature durch ein PDF-1.4-kompatibles Äquivalent, oder zielen Sie auf ein höheres Ausgabeprofil, das das Feature erlaubt.

Pdf20FeatureRejectedException

• Wann sie ausgelöst wird. Der Writer löst dies aus, wenn ein Dokument ein unter dem strikten PDF-2.0-Ausgabeprofil verbotenes Feature enthält. ISO 32000-2:2020 verwirft Konstrukte, die PDF 1.7 noch erlaubte — am bemerkenswertesten die Standard-14-Type-1-Schriften (§9.6.2), die in einem konformen PDF-2.0-Dokument eingebettet sein müssen.
• Getragene Daten. Dieselbe Form wie Pdf14FeatureRejectedException: erweitert NextPdfException, überschreibt getContext() nicht (gibt ein leeres Array zurück) und legt feature, reason und isoClause als public readonly- Eigenschaften offen.
• Behebung. Beheben Sie das abgelehnte Feature — betten Sie zum Beispiel die Base-14- Schriften ein — oder nehmen Sie den dokumentierten Notausgang, wo einer existiert (für nicht eingebettete Base-14-Schriften, Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• Wann sie ausgelöst wird. PdfWriter::build() löst dies am Einstiegspunkt aus, wenn der encryptionMode des Dokuments pubkey ist (eine Public-Key-Empfänger- liste), bevor die writer-seitige Public-Key-Stream-Body-Verschlüsselungs-Dispatch verdrahtet ist. Eine Verweigerung vorab verhindert, dass stillschweigend ein unverschlüsseltes PDF ausgegeben wird, das der Aufrufer für verschlüsselt hielt.
• Getragene Daten. Erweitert RuntimeException direkt, ist also nicht kontextbewusst und hat kein getContext(). Es ist eine strikte Verfeinerung der generischen Exception, die dieselbe Stelle zuvor auslöste, sodass bestehende catch (\RuntimeException)-Handler weiter funktionieren.
• Behebung. Verwenden Sie einen unterstützten Verschlüsselungsmodus (passwortbasierte Verschlüsselung) statt der Public-Key-Empfängerliste, oder pinnen Sie auf eine Version, die Public-Key-Verschlüsselung bringt. Behandeln Sie die Ausgabe nicht als verschlüsselt, wenn dies ausgelöst wird.

Reader- und Metadaten-Eingabe

UnsupportedPdfStructureException

• Wann sie ausgelöst wird. Der Objektgraph-Reader löst dies fail-closed aus, wenn ein Eingabe-PDF außerhalb seiner unterstützten Hülle fällt. Der Reader unterstützt klassische Cross-Reference-Tabellen (ISO 32000-2:2020 §7.5.4), Cross-Reference-Streams (§7.5.8), objekt-stream-komprimierte Objekte (§7.5.7), Multi-Revision-/Prev- Ketten (§7.5.6) und Hybrid-Reference-Dateien über /XRefStm (§7.5.8.4). Alles außerhalb dieser Hülle fördert diese Exception zutage statt eines partiellen oder geratenen Parses. Benannte Konstruktoren ordnen sich den Grundfällen zu: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile() und crossReferenceOffsetOutOfBounds().
• Getragene Daten. Erweitert RuntimeException direkt, ist also nicht kontextbewusst und hat kein getContext(). Es legt eine public readonly- reason-Eigenschaft vom Typ UnsupportedPdfStructureReason (ein Enum) offen, sodass Aufrufer auf die genaue Kategorie verzweigen, ohne die Meldung zu parsen; ein optionaler detail-String und ein previous-Throwable können begrenzten, nicht sensiblen Kontext hinzufügen. Die Standardmeldung ist die nicht durchsickernde Zusammenfassung des Grundes.
• Behebung. Verzweigen Sie auf reason. Bei EncryptedDocument führen Sie einen Entschlüsselungsschritt vor dem Lesen aus, da die Entschlüsselung außerhalb des Geltungsbereichs des Readers liegt. Bei DamagedCrossReference, TruncatedFile oder CrossReferenceOffsetOutOfBounds behandeln Sie die Datei als fehlerhaft oder unvollständig und beschaffen oder reparieren Sie die Quelle erneut. Bei CyclicReferenceChain, NonConformantObjectStream oder IrresolvableObjectCollision verletzt die Eingabe das Strukturmodell und kann nicht unverändert gelesen werden.

PacketTooLargeException

• Wann sie ausgelöst wird. Der Streaming-XMP-Metadaten-Reader löst dies aus, wenn ein eingebettetes XMP-Paket die konfigurierte Byte-Obergrenze überschreitet. Es ist ein defensiver Schutz gegen Entity-Expansion- und Quadratic-Blowup-artige Eingaben (eine 128-MB- Peak-Obergrenze gegen gigabyte-große eingebettete XMP).
• Getragene Daten. Erweitert NextPdfException, überschreibt aber nicht getContext(), sodass getContext() ein leeres Array zurückgibt. Die Diagnosedaten liegen auf ihren public readonly-Eigenschaften: byteCount (die beobachtete Byte-Zahl) und cap (die konfigurierte Kappung in Byte). Die Meldung berichtet beide.
• Behebung. Lehnen oder überspringen Sie die überdimensionierten Metadaten als bösartig oder fehlerhaft. Wenn ein legitimes Dokument tatsächlich ein größeres Paket benötigt, erhöhen Sie die konfigurierte Kappung bewusst und wägen Sie das Speichererschöpfungsrisiko ab, vor dem der Schutz existiert.

Siehe auch

• Index der Fehlerreferenz
• Fehlerbehebung zu Schriften und Tagging — für Symptome von NotYetImplementedException, ScriptShaperException und IcuRequirementException.
• Fehlerbehebung zur PDF/A- und PDF/UA-Validierung — für Symptome von Pdf14FeatureRejectedException und Pdf20FeatureRejectedException.
• Fehlerbehebung zu Verschlüsselung und Berechtigungen — für PublicKeyEncryptionUnsupportedException und den EncryptedDocument-Grund des Readers.