Solução de problemas

Visão geral

A bridge lança três tipos de exceção. A exceção que você captura indica o que falhou e se vale repetir a operação ou usar um fallback. Cada fragmento de mensagem abaixo vem do código-fonte.

A hierarquia de exceções

Exceção	Estende	Significado
CloudflareNotAvailableException	NextPDF\Exception\NextPdfException	A bridge não consegue alcançar a edge, ou a configuração está incompleta, e não há fallback utilizável.
CloudflareRenderException	NextPDF\Exception\NextPdfException	O Worker respondeu, mas a renderização falhou (erro de Hypertext Transfer Protocol (HTTP) ou corpo malformado). Nunca recorre ao fallback.
InvalidSpkiPinException	InvalidArgumentException	Uma string de pin de Subject Public Key Info (SPKI) configurada está malformada.

CloudflareSecurityPolicy também lança RuntimeException diretamente para violações de política de entrada e de Uniform Resource Locator (URL). A exceção é lançada antes do envio de qualquer requisição.

Falhas de configuração e de entrada

Fragmento da mensagem	Lançada por	Causa	Correção
incomplete (missing worker_url or api_token)	Renderer (via caminho de fallback)	Tanto workerUrl quanto apiToken estão vazios	Defina ambos e, em seguida, verifique com isValid().
HTML input exceeds maximum size	CloudflareSecurityPolicy::validate()	A entrada em Hypertext Markup Language (HTML) é maior do que maxHtmlSize	Reduza a entrada ou aumente maxHtmlSize deliberadamente.
Base64 data URI exceeds safety limit	CloudflareSecurityPolicy::validate()	Estima-se que um Uniform Resource Identifier (URI) data:;base64, esteja acima de 13631488 bytes	Externalize o recurso; não incorpore binários grandes inline.
meta-refresh redirect which could cause SSRF	CloudflareSecurityPolicy::validate()	Uma tag <meta http-equiv="refresh"> poderia disparar server-side request forgery (SSRF)	Remova a tag; use um redirecionamento do lado do servidor fora do HTML renderizado.
Invalid Worker URL	validateWorkerUrl()	A URL não pode ser analisada ou não tem scheme/host	Forneça uma URL absoluta completa que use Hypertext Transfer Protocol Secure (HTTPS).
Worker URL must use HTTPS	validateWorkerUrl()	O scheme não é HTTPS	Use https://.
private or reserved IP addresses	validateWorkerUrl()	Literal de Internet Protocol (IP) na faixa Request for Comments (RFC) 1918 / loopback / RFC 3927	Aponte para um endpoint público.
hostname resolves to a private or reserved IP	validateWorkerUrl()	Um registro A/AAAA de Domain Name System (DNS) resolvido é privado ou reservado	Corrija o DNS; investigue um possível rebinding.
DNS answer changed since validation	assertPinsStillValid()	O host resolveu para um novo endereço IP entre a verificação e o envio	Resolva novamente; trate como uma possível tentativa de rebinding.

Falhas do lado do Worker

Estas são falhas de CloudflareRenderException. O Worker respondeu, mas a renderização em si falhou. Elas nunca acionam o fallback local porque a edge estava acessível.

Fragmento da mensagem	Causa
Cloudflare Worker returned HTTP <code>: <detail>	Status diferente de 200. O detalhe vem do campo error em JavaScript Object Notation (JSON) ou dos primeiros 200 bytes do corpo.
Worker returned empty or invalid PDF data	A resposta binária não começa com %PDF.
Worker error: <message>	Resposta JSON que carrega um campo error.
JSON response missing "pdf" field	Resposta JSON sem um campo pdf.
Invalid base64-encoded PDF in JSON response	O campo pdf não foi decodificado de base64 para bytes que começam com %PDF.
Invalid JSON response from Worker	O corpo usa Content-Type: application/json, mas não é decodificado em um array.
Unexpected Content-Type from Worker: <type>	Uma resposta 200 cujo Content-Type não é nem application/pdf nem application/json.

Quando você captura uma dessas, inspecione os logs do Worker. A falha está do lado do Worker, não nesta bridge.

Falhas de acessibilidade e de fallback

Estas são falhas de CloudflareNotAvailableException. A bridge não conseguiu usar a edge, e nenhum fallback produziu um arquivo em Portable Document Format (PDF).

Fragmento da mensagem	Causa	Correção
Cloudflare Worker unavailable: <reason>	Erro de transporte com o fallback desabilitado	Habilite fallbackToLocal e conecte uma factory, ou corrija a conectividade.
Artisan is installed but no LocalRendererFactoryInterface was provided	nextpdf/artisan está presente, mas nenhuma factory foi passada	Passe uma LocalRendererFactoryInterface para o construtor.
local Chrome fallback (nextpdf/artisan) is not installed	O fallback está habilitado, nenhuma factory está configurada e o Artisan está ausente	Execute composer require nextpdf/artisan e, em seguida, conecte uma factory.

Quando você fornece um logger PHP Standards Recommendation (PSR)-3 e o caminho de fallback é executado, a bridge registra um warning (Cloudflare render failed, attempting fallback) e, depois, um info (Falling back to local renderer).

Falhas de transporte / pinning

Sintoma	Causa	Correção
InvalidSpkiPinException: Invalid SPKI pin format	Um pin não está no formato sha256/<base64> (ou sha256//<base64>)	Corrija a string do pin.
cURL transport error (<n>): <msg>	Falha no nível do cURL (Transport Layer Security (TLS), DNS, timeout)	Inspecione o número do erro do cURL; se houver pins definidos, confirme que o SPKI servido ainda está pinado.
As renderizações falham imediatamente após a rotação do certificado	O SPKI do novo certificado não está no conjunto de pins	Adicione o novo SPKI como pin de backup antes de rotacionar.
O transporte pinado não é usado apesar dos pins configurados	Nenhuma ResponseFactory PSR-17 foi fornecida	Passe uma ResponseFactory; o transporte pinado a exige.

isAvailable(): comportamento

isAvailable() nunca lança exceção. Ele retorna false quando a configuração é inválida ou quando a sonda HEAD falha ou lança uma exceção. Ele retorna true somente quando a sonda responde com um status abaixo de 500. Um resultado true é apenas um indicativo: o POST subsequente ainda pode falhar com qualquer um dos erros do lado do Worker acima. Não trate uma sonda aprovada como garantia.

Surpresas de limite de taxa

ApiProtection mantém os limites em memória por processo. As contagens não sobrevivem a uma reinicialização e não são compartilhadas entre workers ou nós. Se um nó permite um cliente e outro o nega, isso é esperado. Coloque um store compartilhado à frente do limitador para ter um limite válido em todo o cluster.

Veja também

• /integrations/cloudflare/security-and-operations/ — o runbook operacional e os controles por trás dessas mensagens.
• /integrations/cloudflare/quickstart/ — o padrão canônico de try/catch.
• /integrations/cloudflare/production-usage/ — detalhes sobre a conexão do fallback.