Sorun giderme

Genel bakış

Köprü, üç özel durum türü tetikler. Yakaladığınız özel durum, neyin başarısız olduğunu ve yeniden denemeniz mi yoksa yedek kullanmanız mı gerektiğini gösterir. Aşağıdaki mesaj parçalarının her biri kaynaktan gelir.

Özel durum hiyerarşisi

Özel durum	Türettiği sınıf	Anlamı
CloudflareNotAvailableException	NextPDF\Exception\NextPdfException	Köprü uç ağa ulaşamaz veya yapılandırma eksiktir ve kullanılabilir bir yedek yoktur.
CloudflareRenderException	NextPDF\Exception\NextPdfException	Worker yanıt verdi, ancak işleme başarısız oldu (Hypertext Transfer Protocol (HTTP) hatası veya hatalı biçimli gövde). Hiçbir zaman yedeğe geçmez.
InvalidSpkiPinException	InvalidArgumentException	Yapılandırılmış bir Subject Public Key Info (SPKI) sabitleme dizesi hatalı biçimlidir.

CloudflareSecurityPolicy, girdi ve Uniform Resource Locator (URL) ilkesi ihlallerinde ayrıca doğrudan RuntimeException tetikler. Bu, herhangi bir istek gönderilmeden önce gerçekleşir.

Yapılandırma ve girdi hataları

Mesaj parçası	Tetikleyen	Neden	Çözüm
incomplete (missing worker_url or api_token)	İşleyici (yedek yolu üzerinden)	Ya workerUrl ya da apiToken boş	Her ikisini de ayarlayın, ardından isValid() ile doğrulayın.
HTML input exceeds maximum size	CloudflareSecurityPolicy::validate()	Hypertext Markup Language (HTML) girdisi şu değerden daha uzun: maxHtmlSize	Girdiyi azaltın veya maxHtmlSize değerini bilinçli olarak yükseltin.
Base64 data URI exceeds safety limit	CloudflareSecurityPolicy::validate()	Bir data:;base64, Uniform Resource Identifier (URI) değerinin 13631488 baytı aştığı tahmin ediliyor	Varlığı dışarı taşıyın; büyük ikili dosyaları satır içine yerleştirmeyin.
meta-refresh redirect which could cause SSRF	CloudflareSecurityPolicy::validate()	Bir <meta http-equiv="refresh"> etiketi sunucu taraflı istek sahteciliğini (SSRF) tetikleyebilir	Etiketi kaldırın; işlenen HTML dışında sunucu taraflı bir yönlendirme kullanın.
Invalid Worker URL	validateWorkerUrl()	URL ayrıştırılamıyor veya scheme/host bilgisi eksik	Hypertext Transfer Protocol Secure (HTTPS) kullanan eksiksiz ve mutlak bir URL sağlayın.
Worker URL must use HTTPS	validateWorkerUrl()	Şema HTTPS değil	Şunu kullanın: https://.
private or reserved IP addresses	validateWorkerUrl()	Internet Protocol (IP) sabit değeri Request for Comments (RFC) 1918 / geri döngü / RFC 3927 aralığında	Genel bir uç noktayı hedefleyin.
hostname resolves to a private or reserved IP	validateWorkerUrl()	Çözümlenen bir Domain Name System (DNS) A/AAAA kaydı özel veya ayrılmış	DNS’yi düzeltin; olası yeniden bağlamayı araştırın.
DNS answer changed since validation	assertPinsStillValid()	Ana bilgisayar, denetim ile gönderim arasında yeni bir IP adresine çözümlendi	Yeniden çözümleyin; olası bir yeniden bağlama girişimi olarak değerlendirin.

Worker taraflı hatalar

Bunlar CloudflareRenderException hatalarıdır. Worker yanıt verdi, ancak işlemenin kendisi başarısız oldu. Bunlar hiçbir zaman yerel yedeği tetiklemez çünkü uç ağa erişilebilmiştir.

Mesaj parçası	Neden
Cloudflare Worker returned HTTP <code>: <detail>	Durum kodu 200 değil. Ayrıntı, JavaScript Object Notation (JSON) error alanından veya gövdenin ilk 200 baytından gelir.
Worker returned empty or invalid PDF data	İkili yanıt %PDF ile başlamıyor.
Worker error: <message>	Bir error alanı içeren JSON yanıtı.
JSON response missing "pdf" field	İçinde pdf alanı bulunmayan JSON yanıtı.
Invalid base64-encoded PDF in JSON response	İçindeki pdf alanı, base64 çözüldüğünde %PDF ile başlayan baytlara dönüşmedi.
Invalid JSON response from Worker	Gövde Content-Type: application/json kullanıyor ancak bir diziye dönüşmüyor.
Unexpected Content-Type from Worker: <type>	Bir 200 yanıtı; Content-Type değeri ne application/pdf ne de application/json.

Bunlardan birini yakaladığınızda Worker günlüklerini inceleyin. Hata Worker tarafındadır; köprüden kaynaklanmaz.

Erişilebilirlik ve yedek hataları

Bunlar CloudflareNotAvailableException hatalarıdır. Köprü uç ağı kullanamadı ve hiçbir yedek bir Portable Document Format (PDF) dosyası üretmedi.

Mesaj parçası	Neden	Çözüm
Cloudflare Worker unavailable: <reason>	Yedek devre dışıyken aktarım hatası	Şunu etkinleştirin: fallbackToLocal, ardından bir fabrika bağlayın veya bağlantıyı düzeltin.
Artisan is installed but no LocalRendererFactoryInterface was provided	nextpdf/artisan mevcut ancak hiçbir fabrika sağlanmadı	Yapıcıya bir LocalRendererFactoryInterface geçirin.
local Chrome fallback (nextpdf/artisan) is not installed	Yedek etkin, hiçbir fabrika yapılandırılmamış ve Artisan yok	Önce composer require nextpdf/artisan komutunu çalıştırın, ardından bir fabrika bağlayın.

PHP Standards Recommendation (PSR)-3 uyumlu bir günlükleyici sağladığınızda ve yedek yolu çalıştığında köprü bir warning (Cloudflare render failed, attempting fallback), ardından bir info (Falling back to local renderer) günlüğe kaydeder.

Aktarım / sabitleme hataları

Belirti	Neden	Çözüm
InvalidSpkiPinException: Invalid SPKI pin format	Bir sabitleme sha256/<base64> (veya sha256//<base64>) biçiminde değil	Sabitleme dizesini düzeltin.
cURL transport error (<n>): <msg>	cURL düzeyinde hata (Transport Layer Security (TLS), DNS, zaman aşımı)	cURL hata numarasını inceleyin; sabitlemeler ayarlanmışsa sunulan SPKI’nin hâlâ sabitlenmiş olduğunu doğrulayın.
Sertifika döndürmesinin hemen ardından işlemeler başarısız oluyor	Yeni sertifikanın SPKI değeri sabitleme kümesinde değil	Döndürmeden önce yeni SPKI değerini yedek sabitleme olarak ekleyin.
Sabitlemeler yapılandırılmış olmasına rağmen sabitlenmiş aktarım kullanılmıyor	Hiçbir PSR-17 ResponseFactory sağlanmadı	Bir ResponseFactory geçirin; sabitlenmiş aktarım bunu gerektirir.

isAvailable() davranışı

isAvailable() hiçbir zaman özel durum tetiklemez. false değerini, yapılandırma geçersizse ya da HEAD yoklaması başarısız olur veya bir özel durum tetiklerse döndürür. true değerini yalnızca yoklama 500 değerinin altında bir durumla yanıt verdiğinde döndürür. true sonucu yalnızca bir ipucudur: sonraki POST yine de yukarıdaki Worker taraflı hatalardan biriyle başarısız olabilir. Başarılı bir yoklamayı garanti olarak değerlendirmeyin.

Hız sınırı sürprizleri

ApiProtection, sınırları işlem başına bellekte tutar. Sayımlar yeniden başlatmadan sonra korunmaz ve işleyiciler ya da düğümler arasında paylaşılmaz. Bir düğüm bir istemciye izin verirken başka bir düğüm onu reddederse bu beklenen bir durumdur. Küme genelinde sınır uygulamak için sınırlayıcının önüne paylaşılan bir depo yerleştirin.

Ayrıca bkz.

• /integrations/cloudflare/security-and-operations/ — bu mesajların dayandığı operasyonel çalıştırma kılavuzu ve denetimler.
• /integrations/cloudflare/quickstart/ — standart try/catch deseni.
• /integrations/cloudflare/production-usage/ — yedek bağlama ayrıntıları.