Laufzeit- und Support-Fehler

Geltungsbereich

Diese Einträge dokumentieren die Exceptions, die von der Laufzeit-Support-Schicht ausgelöst werden: die Degradationspolicy, der cURL-gestützte HTTP-Transport, der Resilienz- Circuit-Breaker, der Security-Information-and-Event-Management-(SIEM-)Emitter, das Render-Manifest, die PDF-Inspektion und das Chaos-Engineering-Subsystem.

Die meisten NextPDF-Exceptions erweitern NextPdfException, das ContextAwareExceptionInterface implementiert und getContext(): array für strukturiertes Diagnose-Logging offenlegt. Eine Unterklasse befüllt dieses Array nur dann, wenn sie getContext() überschreibt; die Basis gibt ein leeres Array zurück. Drei Exceptions auf dieser Seite (DegradedException, CircuitBreakerOpenException und InspectException) erweitern PHPs RuntimeException direkt und legen ihre Daten über öffentliche readonly- Eigenschaften statt über getContext() offen. Jeder Eintrag unten nennt die exakten Eigenschaften oder Kontextschlüssel, die die Klasse trägt, übernommen aus dem Quellcode.

Degradationspolicy

`DegradedException`

Ausgelöst, wenn. Die Rendering-Pipeline stößt auf eine degradierte Capability, die die aktive Degradationspolicy verletzt. Unter DegradationPolicy::Strict löst jede High-Impact-Degradation (ComplianceRisk, SemanticLoss oder Blocking) sie aus; unter DegradationPolicy::Balanced löst nur ein Blocking-Impact sie aus.
Klasse. Erweitert RuntimeException direkt (nicht NextPdfException), trägt also kein getContext().
Getragene Daten. Zwei öffentliche readonly-Eigenschaften: $capability (das Capability-Value-Object, das die Ablehnung ausgelöst hat, einschließlich seiner id, status, reason, fallbackTarget und impact) und $policy (die zum Ablehnungszeitpunkt aktive DegradationPolicy). Die Meldung hat die Form Feature "<id>" is <status>: <reason> (policy: <policy>).
Behebung. Inspizieren Sie $capability, um das fehlende Feature und seine Ursache zu identifizieren. Installieren Sie entweder die Komponente, die die Capability benötigt, akzeptieren Sie eine niedrigere-Impact-Konfiguration, oder lockern Sie die Policy von Strict auf Balanced, wenn die Degradation für den Anwendungsfall akzeptabel ist. Rufen Sie $capability->isAvailable() / isDegraded() auf, um nutzerorientierte Nachrichten zu steuern.

HTTP-Transport

Diese drei Exceptions stammen aus dem cURL-gestützten PSR-18-Client und seinem security-bewussten Decorator. Die ersten beiden erweitern NextPdfException, überschreiben aber nicht getContext(), sodass ihr getContext() ein leeres Array zurückgibt; Diagnosedaten werden über den PSR-18-getRequest()-Accessor und das verkettete vorherige Throwable erreicht.

`CurlNetworkException`

Ausgelöst, wenn. Die HTTP-Anfrage kann wegen eines Netzwerkfehlers nicht abgeschlossen werden: Domain-Name-System-(DNS-)Auflösungsfehler, Verbindungstimeout oder Transport-Layer-Security-(TLS-)Handshake-Fehler. Es ist außerdem die Klasse, die der security-bewusste Decorator für eine Security- Ablehnung auslöst (Server-Side-Request-Forgery-Verweigerung, DNS-Rebinding-Verweigerung oder ein abgelehnter Redirect).
Klasse. Implementiert PSR-18 Psr\Http\Client\NetworkExceptionInterface.
Getragene Daten. getRequest() gibt das fehlgeschlagene RequestInterface zurück. Der ursprüngliche Transportfehler, wenn vorhanden, ist das verkettete vorherige Throwable. getContext() gibt ein leeres Array zurück (die Basis-Voreinstellung).
Behebung. Ein Netzwerkfehler kann vorübergehend sein — wiederholen Sie mit Backoff, wenn die Anfrage idempotent ist. Eine Security-Ablehnung ist nicht vorübergehend und muss fail- closed reagieren: Wiederholen Sie nicht; korrigieren Sie stattdessen die Ziel-URL oder die SSRF-Policy. Lesen Sie die Meldung und das vorherige Throwable, um die beiden zu unterscheiden.

`CurlRequestException`

Ausgelöst, wenn. Die Anfrage selbst kann nicht gesendet werden, weil sie fehlerhaft ist, zum Beispiel eine ungültige URL oder eine Anfrage, die die SSRF-Validierung vor jedem Netzwerkaufruf nicht bestanden hat.
Klasse. Implementiert PSR-18 Psr\Http\Client\RequestExceptionInterface.
Getragene Daten. getRequest() gibt das betreffende RequestInterface zurück; die zugrunde liegende Ursache, wenn vorhanden, ist das verkettete vorherige Throwable. getContext() gibt ein leeres Array zurück.
Behebung. Dies ist ein Aufrufer-Eingabe- oder Policy-Defekt, kein vorübergehender Fehler. Wiederholen Sie nicht unverändert. Korrigieren Sie die Anfrage-URL, die Header oder den Body, oder passen Sie die SSRF-Allowlist an, wenn das Ziel legitim erlaubt ist, und stellen Sie die Anfrage dann erneut.

`TransientHttpException`

Ausgelöst, wenn. Intern, innerhalb von SecurityAwareHttpClient, um einen echt vorübergehenden inneren Transportfehler (DNS, Verbindung oder Timeout, ausgelöst vom inneren PSR-18-Client) als für das begrenzte Retry-Budget förderfähig zu kennzeichnen. Es ist die einzige retry-fähige Klasse, die die Retry-Schleife des Decorators erkennt; eine nicht umgewickelte Exception (eine vom Decorator ausgelöste Security-Ablehnung) wird als fatal behandelt.
Klasse. Implementiert PSR-18 Psr\Http\Client\NetworkExceptionInterface. Als @internal markiert — es wird vollständig innerhalb von SecurityAwareHttpClient erzeugt und ausgewickelt und entweicht niemals dem Decorator.
Getragene Daten. getRequest() gibt die fehlgeschlagene Anfrage zurück. Das ursprüngliche innere Transport-ClientExceptionInterface wird als verkettetes vorheriges Throwable (getPrevious()) bewahrt und wortgetreu an den Aufrufer zurückgespielt, sobald das Retry-Budget erschöpft ist, sodass der öffentliche PSR-18-Vertrag unverändert bleibt. getContext() gibt ein leeres Array zurück.
Behebung. Anwendungscode fängt diesen Typ nicht direkt ab. Fangen Sie die zurückgespielte innere Exception ab, die der Decorator nach dem verbrauchten Retry- Budget zurückgibt, und behandeln Sie wiederholte vorübergehende Fehler als ein vorgelagertes Verfügbarkeitsproblem.

Resilienz

`CircuitBreakerOpenException`

Ausgelöst, wenn. Ein CircuitBreaker im Zustand CircuitBreakerState::Open lehnt einen Aufruf fail-fast ab, vor jeder nachgelagerten Invocation. Es existiert, um Aufrufern zu erlauben, „der Remote-Service ist gerade unerreichbar“ (ein vorübergehender Transportfehler, der eine Degradation wert ist) von „der Connection Pool wäre durch diesen Aufruf erschöpft worden“ (fail-fast, kein Netzwerk versucht) zu unterscheiden — die Batch-Denial-of-Service-Minderung, die für Public-Key-Infrastructure- (PKI-)Clients erforderlich ist.
Klasse. Erweitert RuntimeException direkt, trägt also kein getContext().
Getragene Daten. Zwei öffentliche readonly-Eigenschaften: $breakerName (der Bezeichner des offenen Breakers) und $secondsUntilHalfOpen (die ungefähre verbleibende Abkühlzeit, bevor der Breaker auf Half-Open übergeht). Die Meldung hat die Form Circuit breaker "<name>" is OPEN (cooldown ~<n>s remaining); call rejected fail-fast.
Behebung. Hämmern Sie nicht auf den Breaker ein — warten Sie mindestens $secondsUntilHalfOpen, bevor Sie es erneut versuchen, oder degradieren Sie die Operation. Es wurde kein Netzwerkaufruf versucht, daher ist dies kein Beleg, dass der Remote-Service selbst fehlgeschlagen ist; es ist Back-Pressure, die den Connection Pool schützt.

Observability

`SiemEmitterException`

Ausgelöst, wenn. Ein SIEM-Event-Emitter kann einen Datensatz nicht persistieren oder verketten. Es fördert filesystem-seitige Fehler (open, lock, seek, write, fflush, read) und Hash-Chain-Integritätsfehler (chain: Out-of-Order- Index, fehlerhafter Tail-Datensatz oder JSON-Round-Trip-Drift) zutage, die zwischen dem Hash-Chain-Event-Log und den JSON-Lines-Datei-Emitter-Adaptern geteilt werden.
Klasse. Erweitert NextPdfException und überschreibt getContext().
Kontextschlüssel. operation (eines von open, lock, seek, write, fflush, read, chain), path (der Ziel-Log-Pfad) und detail (ein menschenlesbares Detail wie Byte-Zahlen oder erwarteter-gegenüber-tatsächlichem Index). Diese sind außerdem über getOperation(), getPath() und getDetail() erreichbar. Die Meldung hat die Form SIEM emitter <operation> failed for <path>: <detail>.
Behebung. Dies ist durch Infrastruktur oder SecOps umsetzbar, nicht durch Anwendungslogik. Prüfen Sie den Log-Volume-Mount, die Verzeichnisberechtigungen, die verfügbaren File Descriptors und die Filesystem-Gesundheit. Ein chain-Operations- fehler zeigt ein Manipulations- oder Korruptionssignal im Audit-Log an und sollte untersucht und nicht stillschweigend wiederholt werden.

Render-Manifest

`RenderManifestException`

Ausgelöst, wenn. Ein RenderManifest kann wegen eines strukturellen, Typ- oder Schema-Kompatibilitätsfehlers nicht konstruiert, deserialisiert oder gelesen werden. Das Manifest ist ein versionierter öffentlicher Vertrag, der von jedem Transport (CLI, Laravel-Queue, Symfony, die SaaS-API) übermittelt wird, sodass ein fehlerhaftes oder inkompatibles Manifest direkt zutage gefördert statt auf Standardwerte gezwungen wird.
Klasse. Erweitert NextPdfException und überschreibt getContext(). Benannte Konstruktoren setzen einen stabilen maschinenlesbaren Code im SPEC-MANIFEST-*-Namespace:
- RenderManifestException::shape() → SPEC-MANIFEST-001 — Shape- oder Typ- fehler während RenderManifest::fromArray().
- RenderManifestException::incompatibleVersion() → SPEC-MANIFEST-002 — inkompatible Major-Schema-Version (kann nicht gelesen werden).
- RenderManifestException::missingField() → SPEC-MANIFEST-003 — Pflicht- feld fehlt während der Builder-Finalisierung.
- RenderManifestException::unsupported() → SPEC-MANIFEST-004 — ein wohlgeformtes Manifest referenziert eine Eingabe oder ein Template, das der aktuelle Renderer nicht auflösen kann (zum Beispiel eine URI-Eingabe oder eine host-only-Template-Engine).
Kontextschlüssel. manifest_code (der SPEC-MANIFEST-*-Bezeichner) und reason (die menschenlesbare Fehlerbeschreibung). Diese sind außerdem über getManifestCode() und getReason() erreichbar. Die Meldung hat die Form [<code>] <reason>.
Behebung. Verzweigen Sie auf manifest_code. Bei SPEC-MANIFEST-001 und SPEC-MANIFEST-003 korrigieren Sie die Manifest-Payload (korrigieren Sie den Feldtyp oder liefern Sie das fehlende Feld). Bei SPEC-MANIFEST-002 erzeugen Sie das Manifest gegen eine unterstützte Major-Schema-Version neu oder aktualisieren Sie den Renderer. Bei SPEC-MANIFEST-004 liefern Sie eine Eingabe oder Template-Engine, die die aktuelle Edition auflösen kann.

Inspektion

`InspectException`

Ausgelöst, wenn. Die PDF-Inspektion schlägt fehl.
Klasse. Erweitert RuntimeException direkt (nicht NextPdfException), trägt also kein getContext().
Getragene Daten. Zwei öffentliche readonly-Eigenschaften: $inspectCode (ein maschinenlesbarer Code im INSPECT-*-Namespace) und $retryable (ein Boolean, der angibt, ob der Aufrufer es erneut versuchen sollte — zum Beispiel, wenn ein Inspektions-Sidecar vorübergehend ausgefallen ist). Die ursprüngliche Ursache, wenn vorhanden, ist das verkettete vorherige Throwable.
Behebung. Verzweigen Sie auf $inspectCode für die spezifische Fehlerklasse. Wenn $retryable true ist, wiederholen Sie mit Backoff, weil der Fehler voraussichtlich vorübergehend ist (etwa ein Sidecar-Neustart); wenn false, behandeln Sie die Eingabe oder Konfiguration als Defekt und wiederholen Sie nicht unverändert.

Chaos-Engineering

`ChaosReportWriteException`

Ausgelöst, wenn. ChaosScenarioRunner::writeReport() kann den aggregierten Chaos-Day-Report nicht auf die Festplatte persistieren. Es ist ein domänen-typisierter Ersatz für einen generischen Laufzeitfehler, sodass Aufrufer den spezifischen Report-Disk-Fehler abfangen können, ohne ihn mit Fehlern zu vermengen, die innerhalb der Szenario-Simulatoren selbst ausgelöst werden (der Runner erfasst diese als ChaosOutcome-Felder).
Klasse. Erweitert NextPdfException und überschreibt getContext().
Kontextschlüssel. output_path (der absolute Pfad, den der Runner zu schreiben versuchte). Es ist außerdem über getOutputPath() erreichbar. Die Meldung hat die Form ChaosScenarioRunner: failed to write report to "<path>".
Behebung. Dies ist ein schreibseitiger Fehler der Report-Senke, nicht der Szenarien. Prüfen Sie, ob das Ausgabeverzeichnis existiert und beschreibbar ist und ob Speicher- platz verfügbar ist, und führen Sie dann den Report-Schreibvorgang erneut aus. Die Chaos-Outcomes selbst sind nicht betroffen.

`RetrievalUnavailableException`

Ausgelöst, wenn. Ein Retrieval-Endpunkt (zum Beispiel ein Voyage-Retrieval- Augmented-Generation-Service) ist nicht verfügbar, und das System fällt entweder auf cached-only-Modus zurück oder reagiert fail-closed.
Klasse. Erweitert NextPdfException und überschreibt getContext().
Kontextschlüssel. mode (der Betriebsmodus nach dem Fehler — CACHED_ONLY, wenn Ergebnisse nur aus dem semantischen Cache geliefert werden, oder FAIL_CLOSED, wenn die Anfrage vollständig ohne veraltete Daten verweigert wird) und endpoint (der Endpunkt, der unerreichbar wurde). Diese sind außerdem über getMode() und getEndpoint() erreichbar. Die Meldung hat die Form Retrieval endpoint "<endpoint>" is unavailable; operating in <mode> mode.
Behebung. Lesen Sie mode, um zu erfahren, wie das System degradiert ist. Unter CACHED_ONLY können Ergebnisse veraltet sein; aktualisieren Sie sie, sobald der Endpunkt sich erholt. Unter FAIL_CLOSED wurde die Anfrage absichtlich verweigert und muss nach Erreichbarkeit des Endpunkts erneut versucht werden. Stellen Sie die Endpunkt-Konnektivität (Netzwerk, Anmeldedaten, Service-Gesundheit) wieder her, bevor Sie sich auf frisches Retrieval verlassen.

Laufzeit- und Support-Fehler

Geltungsbereich

Degradationspolicy

DegradedException

HTTP-Transport

CurlNetworkException

CurlRequestException

TransientHttpException

Resilienz

CircuitBreakerOpenException