Pemecahan masalah

Sekilas

Bridge memicu tiga jenis pengecualian. Pengecualian yang Anda tangkap memberi tahu bagian mana yang gagal dan apakah Anda perlu mencoba lagi atau menggunakan fallback. Setiap fragmen pesan di bawah ini berasal dari kode sumber.

Hierarki pengecualian

Pengecualian	Memperluas	Arti
CloudflareNotAvailableException	NextPDF\Exception\NextPdfException	Bridge tidak dapat menjangkau edge atau konfigurasinya tidak lengkap, dan tidak ada fallback yang dapat digunakan.
CloudflareRenderException	NextPDF\Exception\NextPdfException	Worker merespons, tetapi proses render gagal (kesalahan Hypertext Transfer Protocol (HTTP) atau bodi yang tidak valid). Tidak pernah menjalankan fallback.
InvalidSpkiPinException	InvalidArgumentException	String pin Subject Public Key Info (SPKI) yang dikonfigurasi tidak valid.

CloudflareSecurityPolicy juga memicu RuntimeException secara langsung untuk pelanggaran kebijakan input dan Uniform Resource Locator (URL). Pengecualian ini dipicu sebelum permintaan apa pun dikirim.

Kegagalan konfigurasi dan input

Fragmen pesan	Dipicu oleh	Penyebab	Perbaikan
incomplete (missing worker_url or api_token)	renderer (melalui jalur fallback)	Salah satu dari workerUrl atau apiToken kosong	Atur keduanya, lalu verifikasi dengan isValid().
HTML input exceeds maximum size	CloudflareSecurityPolicy::validate()	Input Hypertext Markup Language (HTML) melebihi maxHtmlSize	Kurangi input atau naikkan maxHtmlSize secara sengaja.
Base64 data URI exceeds safety limit	CloudflareSecurityPolicy::validate()	Uniform Resource Identifier (URI) data:;base64, diperkirakan melebihi 13631488 bita	Eksternalkan aset; jangan sisipkan biner besar secara inline.
meta-refresh redirect which could cause SSRF	CloudflareSecurityPolicy::validate()	Tag <meta http-equiv="refresh"> dapat memicu server-side request forgery (SSRF)	Hapus tag tersebut; gunakan pengalihan sisi server di luar HTML yang dirender.
Invalid Worker URL	validateWorkerUrl()	URL tidak dapat diuraikan atau tidak memiliki scheme/host	Sediakan URL absolut lengkap yang menggunakan Hypertext Transfer Protocol Secure (HTTPS).
Worker URL must use HTTPS	validateWorkerUrl()	Skema bukan HTTPS	Gunakan https://.
private or reserved IP addresses	validateWorkerUrl()	Literal Internet Protocol (IP) berada dalam rentang Request for Comments (RFC) 1918 / loopback / RFC 3927	Arahkan ke endpoint publik.
hostname resolves to a private or reserved IP	validateWorkerUrl()	Record A/AAAA Domain Name System (DNS) yang teresolusi mengarah ke alamat privat atau dicadangkan	Perbaiki DNS; selidiki kemungkinan rebinding.
DNS answer changed since validation	assertPinsStillValid()	Host teresolusi ke alamat IP baru antara pemeriksaan dan pengiriman	Lakukan resolusi ulang; perlakukan sebagai kemungkinan upaya rebinding.

Kegagalan sisi Worker

Ini adalah kegagalan CloudflareRenderException. Worker merespons, tetapi proses render itu sendiri gagal. Kegagalan ini tidak pernah memicu fallback lokal karena edge dapat dijangkau.

Fragmen pesan	Penyebab
Cloudflare Worker returned HTTP <code>: <detail>	Status non-200. Detail berasal dari bidang error JavaScript Object Notation (JSON) atau 200 bita pertama dari bodi.
Worker returned empty or invalid PDF data	Respons biner tidak diawali dengan %PDF.
Worker error: <message>	Respons JSON yang berisi bidang error.
JSON response missing "pdf" field	Respons JSON tanpa bidang pdf.
Invalid base64-encoded PDF in JSON response	Bidang pdf tidak dapat di-decode dari base64 menjadi bita yang diawali dengan %PDF.
Invalid JSON response from Worker	Bodi menggunakan Content-Type: application/json, tetapi tidak dapat di-decode menjadi larik.
Unexpected Content-Type from Worker: <type>	Respons 200 dengan Content-Type yang bukan application/pdf maupun application/json.

Jika Anda menangkap salah satunya, periksa log Worker. Kegagalan berada di sisi Worker, bukan di bridge ini.

Kegagalan keterjangkauan dan fallback

Ini adalah kegagalan CloudflareNotAvailableException. Bridge tidak dapat menggunakan edge, dan tidak ada fallback yang dapat menghasilkan berkas Portable Document Format (PDF).

Fragmen pesan	Penyebab	Perbaikan
Cloudflare Worker unavailable: <reason>	Kesalahan transport saat fallback dinonaktifkan	Aktifkan fallbackToLocal dan sambungkan factory, atau perbaiki konektivitas.
Artisan is installed but no LocalRendererFactoryInterface was provided	nextpdf/artisan tersedia, tetapi tidak ada factory yang diberikan	Teruskan LocalRendererFactoryInterface ke konstruktor.
local Chrome fallback (nextpdf/artisan) is not installed	Fallback diaktifkan, tidak ada factory yang dikonfigurasi, dan Artisan tidak terpasang	Jalankan composer require nextpdf/artisan, lalu sambungkan factory.

Saat Anda menyediakan logger PHP Standards Recommendation (PSR)-3 dan jalur fallback berjalan, bridge mencatat warning (Cloudflare render failed, attempting fallback), lalu info (Falling back to local renderer).

Kegagalan transport / pinning

Gejala	Penyebab	Perbaikan
InvalidSpkiPinException: Invalid SPKI pin format	Salah satu pin tidak berbentuk sha256/<base64> (atau sha256//<base64>)	Perbaiki string pin.
cURL transport error (<n>): <msg>	Kegagalan tingkat cURL (Transport Layer Security (TLS), DNS, batas waktu)	Periksa nomor kesalahan cURL; jika pin diatur, pastikan SPKI yang disajikan masih tercakup dalam pin.
Render gagal segera setelah rotasi sertifikat	SPKI sertifikat baru tidak ada dalam set pin	Tambahkan SPKI baru sebagai pin cadangan sebelum rotasi.
Transport dengan pinning tidak digunakan meskipun pin telah dikonfigurasi	Tidak ada ResponseFactory PSR-17 yang disediakan	Teruskan ResponseFactory; transport dengan pinning membutuhkannya.

Perilaku isAvailable()

isAvailable() tidak pernah melempar pengecualian. Metode ini mengembalikan false ketika konfigurasi tidak valid, atau ketika probe HEAD gagal atau memicu pengecualian. Metode ini mengembalikan true hanya ketika probe merespons dengan status di bawah 500. Hasil true hanyalah petunjuk: POST berikutnya tetap dapat gagal dengan salah satu kesalahan sisi Worker di atas. Jangan menganggap probe yang lolos sebagai jaminan.

Hal tak terduga pada rate-limit

ApiProtection menyimpan batas dalam memori per proses. Penghitung tidak bertahan setelah restart, dan tidak dibagikan di antara worker atau node. Jika satu node mengizinkan sebuah klien dan node lain menolaknya, hal itu memang diharapkan. Gunakan penyimpanan bersama di depan limiter untuk batas yang berlaku di seluruh cluster.

Lihat juga

• /integrations/cloudflare/security-and-operations/ — runbook operasional dan kontrol yang mendasari pesan-pesan ini.
• /integrations/cloudflare/quickstart/ — pola try/catch kanonis.
• /integrations/cloudflare/production-usage/ — detail penyambungan fallback.