Fehlerbehebung

Auf einen Blick

Die Bridge löst drei Ausnahmetypen aus. Anhand des abgefangenen Typs erkennen Sie, was fehlgeschlagen ist und ob ein erneuter Versuch oder ein Fallback angebracht ist. Alle unten aufgeführten Meldungsfragmente stammen aus dem Quellcode.

Die Ausnahmehierarchie

Ausnahme	Erweitert	Bedeutung
CloudflareNotAvailableException	NextPDF\Exception\NextPdfException	Der Edge ist nicht erreichbar oder die Konfiguration ist unvollständig; es steht kein nutzbarer Fallback zur Verfügung.
CloudflareRenderException	NextPDF\Exception\NextPdfException	Der Worker hat geantwortet, doch das Rendering ist fehlgeschlagen (HTTP-Fehler oder fehlerhafter Body). Löst niemals einen Fallback aus.
InvalidSpkiPinException	InvalidArgumentException	Eine konfigurierte SPKI-Pin-Zeichenfolge ist ungültig.

CloudflareSecurityPolicy löst bei Verstößen gegen Eingabe- und URL-Richtlinien außerdem direkt RuntimeException aus. Dies geschieht, bevor eine Anfrage gesendet wird.

Konfigurations- und Eingabefehler

Meldungsfragment	Ausgelöst von	Ursache	Behebung
incomplete (missing worker_url or api_token)	Renderer (über den Fallback-Pfad)	workerUrl oder apiToken ist leer	Setzen Sie beide Werte; überprüfen Sie die Konfiguration mit isValid().
HTML input exceeds maximum size	CloudflareSecurityPolicy::validate()	HTML ist länger als maxHtmlSize	Reduzieren Sie die Eingabe oder erhöhen Sie maxHtmlSize gezielt.
Base64 data URI exceeds safety limit	CloudflareSecurityPolicy::validate()	Ein data:;base64,-URI, dessen geschätzte Größe über 13631488 Bytes liegt	Lagern Sie das Asset aus; betten Sie keine großen Binärdaten inline ein.
meta-refresh redirect which could cause SSRF	CloudflareSecurityPolicy::validate()	Ein <meta http-equiv="refresh">-Tag	Entfernen Sie das Tag; verwenden Sie einen serverseitigen Redirect außerhalb des gerenderten HTML.
Invalid Worker URL	validateWorkerUrl()	URL lässt sich nicht parsen oder scheme/host fehlt	Geben Sie eine vollständige absolute HTTPS-URL an.
Worker URL must use HTTPS	validateWorkerUrl()	Nicht-HTTPS-Schema	Verwenden Sie https://.
private or reserved IP addresses	validateWorkerUrl()	IP-Literal im Bereich RFC 1918 / Loopback / RFC 3927	Verweisen Sie auf einen öffentlichen Endpunkt.
hostname resolves to a private or reserved IP	validateWorkerUrl()	Ein aufgelöster A-/AAAA-Eintrag ist private/reserved	Beheben Sie das DNS; untersuchen Sie ein mögliches Rebinding.
DNS answer changed since validation	assertPinsStillValid()	Der Host wurde zwischen Prüfung und Senden auf eine neue IP aufgelöst	Führen Sie die Auflösung erneut durch; behandeln Sie dies als möglichen Rebinding-Versuch.

Worker-seitige Fehler

Hierbei handelt es sich um CloudflareRenderException. Der Worker hat geantwortet, doch das Rendering selbst ist fehlgeschlagen. Diese Fehler lösen niemals den lokalen Fallback aus — der Edge war erreichbar.

Meldungsfragment	Ursache
Cloudflare Worker returned HTTP <code>: <detail>	Der Status ist nicht 200. Das Detail ist das JSON-Feld error oder die ersten 200 Body-Bytes.
Worker returned empty or invalid PDF data	Binärantwort, die nicht mit %PDF beginnt.
Worker error: <message>	JSON-Antwort, die ein error-Feld enthält.
JSON response missing "pdf" field	JSON-Antwort ohne pdf-Feld.
Invalid base64-encoded PDF in JSON response	Das pdf-Feld ließ sich per Base64 nicht zu Bytes dekodieren, die mit %PDF beginnen.
Invalid JSON response from Worker	Content-Type: application/json, aber der Body ließ sich nicht zu einem Array dekodieren.
Unexpected Content-Type from Worker: <type>	Eine 200-Antwort, deren Content-Type weder application/pdf noch application/json ist.

Wenn Sie einen dieser Fehler abfangen, prüfen Sie die Worker-Logs. Der Fehler liegt auf der Worker-Seite, nicht in dieser Bridge.

Erreichbarkeits- und Fallback-Fehler

Hierbei handelt es sich um CloudflareNotAvailableException. Der Edge konnte nicht genutzt werden, und kein Fallback hat ein PDF erzeugt.

Meldungsfragment	Ursache	Behebung
Cloudflare Worker unavailable: <reason>	Transportfehler, Fallback deaktiviert	Aktivieren Sie fallbackToLocal und binden Sie eine Factory an, oder beheben Sie die Konnektivität.
Artisan is installed but no LocalRendererFactoryInterface was provided	nextpdf/artisan vorhanden, keine Factory übergeben	Übergeben Sie ein LocalRendererFactoryInterface an den Konstruktor.
local Chrome fallback (nextpdf/artisan) is not installed	Fallback aktiviert, keine Factory, Artisan nicht vorhanden	composer require nextpdf/artisan und binden Sie eine Factory an.

Wenn Sie einen PSR-3-Logger bereitstellen und der Fallback-Pfad ausgeführt wird, protokolliert die Bridge zunächst eine warning (Cloudflare render failed, attempting fallback) und anschließend ein info (Falling back to local renderer).

Transport- / Pinning-Fehler

Symptom	Ursache	Behebung
InvalidSpkiPinException: Invalid SPKI pin format	Ein Pin, der nicht in der Form sha256/<base64> (oder sha256//<base64>) vorliegt	Korrigieren Sie die Pin-Zeichenfolge.
cURL transport error (<n>): <msg>	Fehler auf cURL-Ebene (TLS, DNS, Timeout)	Prüfen Sie die cURL-Fehlernummer; wenn Pins gesetzt sind, stellen Sie sicher, dass der ausgelieferte SPKI weiterhin gepinnt ist.
Renderings schlagen unmittelbar nach einer Zertifikatsrotation fehl	Der SPKI des neuen Zertifikats ist nicht im Pin-Satz enthalten	Fügen Sie den neuen SPKI vor der Rotation als Backup-Pin hinzu.
Der gepinnte Transport wird trotz konfigurierter Pins nicht verwendet	Es wurde keine PSR-17-ResponseFactory bereitgestellt	Übergeben Sie eine ResponseFactory; der gepinnte Transport benötigt sie.

isAvailable()-Verhalten

isAvailable() löst niemals eine Ausnahme aus. Es gibt false zurück, wenn die Konfiguration ungültig ist, die HEAD-Probe fehlschlägt oder eine Ausnahme auslöst. Es gibt nur dann true zurück, wenn die Probe mit einem Status unter 500 antwortet. Ein true-Ergebnis ist nur ein Hinweis: Der nachfolgende POST kann weiterhin mit einem der oben genannten Worker-seitigen Fehler fehlschlagen. Behandeln Sie eine bestandene Probe nicht als Garantie.

Überraschungen bei der Ratenbegrenzung

Der ApiProtection-Limiter arbeitet im prozesslokalen Arbeitsspeicher. Die Zähler überstehen keinen Neustart und werden nicht über Worker oder Nodes hinweg geteilt. Wenn Sie also beobachten, dass ein Client auf einem Node zugelassen und auf einem anderen abgelehnt wird, ist das zu erwarten. Setzen Sie vor den Limiter einen gemeinsam genutzten Speicher, um eine clusterweite Begrenzung zu erreichen.

Siehe auch

• /integrations/cloudflare/security-and-operations/ — das Betriebs-Runbook und die Kontrollen hinter diesen Meldungen.
• /integrations/cloudflare/quickstart/ — die kanonische try/catch-Form.
• /integrations/cloudflare/production-usage/ — Details zur Fallback-Verdrahtung.