Probleemoplossing

In één oogopslag

De bridge kan drie soorten uitzonderingen veroorzaken. De uitzondering die je opvangt, vertelt wat er is mislukt en of je het opnieuw moet proberen of een fallback moet gebruiken. Elk berichtfragment hieronder komt uit de broncode.

De uitzonderingshiërarchie

Uitzondering	Breidt uit	Betekenis
CloudflareNotAvailableException	NextPDF\Exception\NextPdfException	De bridge kan de edge niet bereiken of de configuratie is onvolledig, en er is geen bruikbare fallback beschikbaar.
CloudflareRenderException	NextPDF\Exception\NextPdfException	De Worker heeft geantwoord, maar de weergave is mislukt (Hypertext Transfer Protocol (HTTP)-fout of onjuist gevormde body). Activeert nooit een fallback.
InvalidSpkiPinException	InvalidArgumentException	Een geconfigureerde Subject Public Key Info (SPKI)-pinstring is onjuist gevormd.

CloudflareSecurityPolicy gooit ook rechtstreeks RuntimeException bij schendingen van het invoerbeleid en Uniform Resource Locator (URL)-beleid. Dat gebeurt voordat er een verzoek wordt verstuurd.

Configuratie- en invoerfouten

Berichtfragment	Veroorzaakt door	Oorzaak	Oplossing
incomplete (missing worker_url or api_token)	Renderer (via fallbackpad)	Ofwel workerUrl ofwel apiToken is leeg	Stel beide in en verifieer vervolgens met isValid().
HTML input exceeds maximum size	CloudflareSecurityPolicy::validate()	De Hypertext Markup Language (HTML)-invoer is langer dan maxHtmlSize	Verklein de invoer, of verhoog maxHtmlSize bewust.
Base64 data URI exceeds safety limit	CloudflareSecurityPolicy::validate()	Een data:;base64, Uniform Resource Identifier (URI) wordt op meer dan 13631488 bytes geschat	Plaats de asset extern; neem grote binaire bestanden niet inline op.
meta-refresh redirect which could cause SSRF	CloudflareSecurityPolicy::validate()	Een <meta http-equiv="refresh">-tag kan server-side request forgery (SSRF) veroorzaken	Verwijder de tag; gebruik een server-side redirect buiten de weergegeven HTML.
Invalid Worker URL	validateWorkerUrl()	De URL kan niet worden geparseerd of mist een scheme/host	Geef een volledige absolute URL op met Hypertext Transfer Protocol Secure (HTTPS).
Worker URL must use HTTPS	validateWorkerUrl()	Het scheme is geen HTTPS	Gebruik https://.
private or reserved IP addresses	validateWorkerUrl()	Een Internet Protocol (IP)-literal valt binnen Request for Comments (RFC) 1918 / loopback / RFC 3927	Verwijs naar een openbaar endpoint.
hostname resolves to a private or reserved IP	validateWorkerUrl()	Een omgezet Domain Name System (DNS) A/AAAA-record is privé of gereserveerd	Corrigeer DNS; onderzoek mogelijke rebinding.
DNS answer changed since validation	assertPinsStillValid()	De host is tussen controle en verzending omgezet naar een nieuw IP-adres	Voer de omzetting opnieuw uit; behandel dit als een mogelijke rebindingpoging.

Fouten aan de Worker-zijde

Dit zijn fouten van het type CloudflareRenderException. De Worker heeft geantwoord, maar de weergave zelf is mislukt. Deze activeren nooit de lokale fallback, omdat de edge bereikbaar was.

Berichtfragment	Oorzaak
Cloudflare Worker returned HTTP <code>: <detail>	Een andere statuscode dan 200. Het detail komt uit het JavaScript Object Notation (JSON)-veld error of de eerste 200 bytes van de body.
Worker returned empty or invalid PDF data	Het binaire antwoord begint niet met %PDF.
Worker error: <message>	Een JSON-antwoord dat een error-veld bevat.
JSON response missing "pdf" field	Een JSON-antwoord zonder pdf-veld.
Invalid base64-encoded PDF in JSON response	Het pdf-veld kan via base64 niet worden gedecodeerd naar bytes die beginnen met %PDF.
Invalid JSON response from Worker	De body gebruikt Content-Type: application/json, maar kan niet naar een array worden gedecodeerd.
Unexpected Content-Type from Worker: <type>	Een 200-antwoord waarbij de Content-Type noch application/pdf noch application/json is.

Wanneer je een van deze opvangt, raadpleeg dan de Worker-logs. De fout ligt aan de Worker-zijde, niet in deze bridge.

Bereikbaarheids- en fallbackfouten

Dit zijn fouten van het type CloudflareNotAvailableException. De bridge kon de edge niet gebruiken en geen enkele fallback leverde een Portable Document Format (PDF)-bestand op.

Berichtfragment	Oorzaak	Oplossing
Cloudflare Worker unavailable: <reason>	Transportfout terwijl de fallback is uitgeschakeld	Schakel fallbackToLocal in en koppel een factory, of herstel de connectiviteit.
Artisan is installed but no LocalRendererFactoryInterface was provided	nextpdf/artisan is aanwezig, maar er is geen factory doorgegeven	Geef een LocalRendererFactoryInterface door aan de constructor.
local Chrome fallback (nextpdf/artisan) is not installed	De fallback is ingeschakeld, er is geen factory geconfigureerd en Artisan ontbreekt	Voer composer require nextpdf/artisan uit en koppel vervolgens een factory.

Wanneer je een PHP Standards Recommendation (PSR)-3-logger opgeeft en het fallbackpad wordt uitgevoerd, registreert de bridge een warning (Cloudflare render failed, attempting fallback) en vervolgens een info (Falling back to local renderer).

Transport- / pinningfouten

Symptoom	Oorzaak	Oplossing
InvalidSpkiPinException: Invalid SPKI pin format	Een pin heeft niet de vorm sha256/<base64> (of sha256//<base64>)	Corrigeer de pinstring.
cURL transport error (<n>): <msg>	Fout op cURL-niveau (Transport Layer Security (TLS), DNS, time-out)	Bekijk het cURL-foutnummer; als er pins zijn ingesteld, controleer dan of de geleverde SPKI nog steeds is gepind.
Weergaven mislukken direct na certificaatrotatie	De SPKI van het nieuwe certificaat staat niet in de pinset	Voeg de nieuwe SPKI als back-uppin toe voordat je roteert.
Gepind transport wordt niet gebruikt ondanks geconfigureerde pins	Er is geen PSR-17 ResponseFactory opgegeven	Geef een ResponseFactory door; het gepinde transport vereist dit.

Gedrag van isAvailable()

isAvailable() gooit nooit een uitzondering. Het retourneert false wanneer de configuratie ongeldig is of wanneer de HEAD-probe mislukt of een uitzondering gooit. Het retourneert alleen true wanneer de probe reageert met een status lager dan 500. Een resultaat true is slechts een aanwijzing: de daaropvolgende POST kan nog steeds mislukken met een van de fouten aan de Worker-zijde hierboven. Beschouw een geslaagde probe niet als een garantie.

Verrassingen met rate-limiting

ApiProtection houdt limieten per proces bij in het geheugen. Tellers blijven niet behouden na een herstart en worden niet gedeeld tussen workers of nodes. Als de ene node een client toestaat en een andere deze weigert, is dat te verwachten. Gebruik een gedeelde store voor de limiter voor een clusterbrede limiet.

Zie ook

• /integrations/cloudflare/security-and-operations/ — het operationele runbook en de beheersmaatregelen achter deze berichten.
• /integrations/cloudflare/quickstart/ — het canonieke try/catch-patroon.
• /integrations/cloudflare/production-usage/ — details over het aansluiten van de fallback.