Pemecahan masalah NextPDF Gotenberg

Sekilas

Bridge gagal secara eksplisit dan sedini mungkin. Setiap kegagalan melempar pengecualian bertipe dengan pesan yang menyebutkan penyebabnya. Gunakan halaman ini sebagai katalog. Untuk setiap kegagalan, Anda akan melihat tipe pengecualian, fragmen pesan yang muncul, pemicu pastinya pada jalur kode, dan perbaikannya.

Keluarga pengecualian tersebut adalah:

GotenbergConvertException — kegagalan pada lapisan konversi (konfigurasi, transport, atau respons).
RuntimeException — kegagalan pada lapisan validasi yang dilempar oleh kebijakan keamanan sebelum lalu lintas jaringan terjadi.
ValueError — ekstensi berkas yang tidak dikenali.
InvalidSpkiPinException — string pin Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) dengan format yang salah.

Kegagalan konfigurasi

”Konfigurasi Gotenberg tidak valid: apiUrl kosong”

Tipe: GotenbergConvertException
Pemicu: Anda memanggil convertFile() atau convertString() ketika GotenbergConfig::isValid() bernilai false. Ini terjadi ketika apiUrl adalah string kosong.
Perbaikan: Sediakan URL HTTPS yang tidak kosong. Jika Anda membangun konfigurasi dengan fromArray(), perhatikan bahwa metode itu secara diam-diam mengisi '' untuk api_url yang hilang atau bukan string. Validasi sumber konfigurasi Anda saat boot.

Kegagalan URL dan alamat (SSRF)

Kegagalan ini berasal dari kebijakan keamanan, yang melindungi dari server-side request forgery (SSRF). Bridge memunculkannya sebelum mengirim permintaan apa pun. Masing-masing berupa RuntimeException biasa.

”URL API Gotenberg harus menggunakan HTTPS (didapat: http)”

Pemicu: Skema URL yang dikonfigurasi bukan https. Pemeriksaan tidak membedakan huruf besar-kecil, jadi HTTPS:// diterima.
Perbaikan: Tempatkan Gotenberg di belakang TLS dan konfigurasikan endpoint HTTPS. HTTP biasa ditolak bahkan untuk pengembangan lokal.

”URL API Gotenberg tidak valid: tidak dapat diuraikan”

Pemicu: URL tidak dapat diuraikan menjadi skema dan host.
Perbaikan: Berikan URL absolut yang valid secara sintaksis, misalnya https://gotenberg.example.com:3000.

”URL API Gotenberg tidak boleh me-resolve ke alamat IP privat atau yang dicadangkan”

Pemicu: Host berupa literal Internet Protocol (IP) privat atau yang dicadangkan, atau nama host yang me-resolve (melalui semua rekaman A/AAAA) ke alamat privat atau alamat yang dicadangkan mana pun. Ini memblokir rentang privat dari Request for Comments (RFC) 1918, loopback, dan alamat link-local.
Perbaikan: Arahkan bridge ke alamat publik yang routable atau alamat layanan yang tersegmentasi dengan benar. Jika Gotenberg Anda memang sengaja berada di jaringan privat, pelindung SSRF bridge menolaknya secara desain. Ekspos melalui alamat yang diterima pelindung, lalu lindungi jalur tersebut dengan kontrol jaringan dan autentikasi. Lihat /integrations/gotenberg/security-and-operations/.

”Jawaban DNS URL API Gotenberg berubah sejak validasi — kemungkinan serangan DNS rebinding”

Pemicu: Di antara validasi awal dan permintaan, resolusi Domain Name System (DNS) terbaru mengembalikan alamat yang tidak ada dalam kumpulan alamat yang semula divalidasi.
Perbaikan: Ini adalah pelindung time-of-check/time-of-use yang aktif. Selidiki DNS untuk host tersebut. Penyebab yang sah adalah load balancer yang merotasi alamat. Penyebab yang berbahaya adalah serangan rebinding. Gunakan alamat yang stabil atau nama dengan kumpulan rekaman yang stabil untuk endpoint Gotenberg.

Kegagalan validasi input

Kebijakan keamanan memunculkan kegagalan ini sebelum permintaan dikirim. Masing-masing berupa RuntimeException biasa kecuali dinyatakan lain.

”Berkas tidak ditemukan atau tidak dapat dibaca: ”

Tipe: GotenbergConvertException
Pemicu: convertFile() tidak dapat melakukan kanonikalisasi pada path, atau path yang di-resolve bukan berkas reguler yang dapat dibaca. Direktori juga memicu ini.
Perbaikan: Berikan path ke berkas yang ada dan dapat dibaca. Path dikanonikalisasi dengan realpath() terlebih dahulu, yang sekaligus menggagalkan traversal.

”Ukuran berkas ( byte) melebihi ukuran maksimum yang diizinkan ( byte)”

Pemicu: Input lebih besar daripada maxFileSize (standar 52.428.800 byte = 50 MiB).
Perbaikan: Naikkan maxFileSize jika dokumen memang membutuhkannya secara sah, atau tolak unggahan di hulu. Pertahankan batas serendah mungkin yang masih mengakomodasi dokumen nyata Anda. Ini adalah satu-satunya batas sumber daya bawaan bridge.

Penolakan nama berkas

Bridge memvalidasi nama berkas. Untuk konversi berkas, nama berkas adalah basename dari path yang di-resolve; untuk convertString(), nama tersebut adalah nama yang Anda berikan. Masing-masing berupa RuntimeException:

Fragmen pesan	Pemicu
`must not be empty`	nama berkas kosong
`path traversal sequences (..)`	nama mengandung `..`
`forward slashes`	nama mengandung `/`
`backslashes`	nama mengandung `\`
`null bytes`	nama mengandung byte NUL
`control characters`	nama mengandung karakter kontrol ASCII (0–31)

Perbaikan: Berikan basename yang bersih. Untuk convertString(), berikan nama biasa seperti report.docx. Nama tersebut digunakan untuk deteksi format dan sebagai nama berkas unggahan multipart, bukan sebagai path.

”Ekstensi format office tidak dikenal: ”

Tipe: ValueError
Pemicu: Ekstensi berkas bukan salah satu dari docx, xlsx, pptx, odt, ods, odp (tidak peka huruf besar-kecil, titik di depan ditoleransi).
Perbaikan: Konversikan hanya enam format yang dikenali. Bridge tidak mengenali format biner lawas (.doc, .xls, .ppt), .rtf, .csv, teks biasa, atau gambar. Konversikan input ini ke format yang dikenali sebelum Anda memanggil bridge, atau arahkan melalui jalur lain.

Kegagalan transport dan respons

Semua ini berupa GotenbergConvertException.

”Permintaan HTTP Gotenberg gagal: ”

Pemicu: Klien PHP Standard Recommendation 18 (PSR-18) (atau transport cURL ber-pin) melempar pengecualian saat mengirim permintaan. Penyebabnya adalah penolakan koneksi, batas waktu, kegagalan handshake TLS, atau ketidakcocokan pin.
Kode pengecualian: kode pengecualian klien yang mendasarinya.
Penyebab: pengecualian klien PSR-18 asli dilampirkan sebagai pengecualian sebelumnya.
Perbaikan: Periksa empat hal. Periksa keterjangkauan layanan dengan isAvailable(). Periksa jalur jaringan. Periksa rantai TLS. Jika pinning dikonfigurasi, pastikan SubjectPublicKeyInfo (SPKI) server saat ini cocok dengan pin yang dikonfigurasi. Ketidakcocokan pin setelah rotasi sertifikat adalah penyebab klasiknya. Lihat prosedur rotasi di /integrations/gotenberg/security-and-operations/.

”Galat transport cURL (): ”

Pemicu: curl_exec dari transport cURL ber-pin gagal dengan nomor galat cURL bukan nol, atau mengembalikan body yang bukan string.
Perbaikan: Nomor galat cURL menunjukkan penyebabnya (TLS, resolve, batas waktu, pin). Kegagalan pinning muncul di sini ketika CURLOPT_PINNEDPUBLICKEY menolak sertifikat. Pastikan bahwa pin yang dikonfigurasi dan alamat yang di-resolve sudah terkini.

”Konversi Gotenberg gagal dengan HTTP : ”

Pemicu: Status respons bukan 200. Body disertakan, dipangkas hingga 500 karakter pertama, dengan elipsis ditambahkan jika lebih panjang.
Perbaikan: Baca body yang disertakan. Pesan galat Gotenberg menjelaskan mengapa konversi ditolak: konten dokumen yang tidak didukung, kegagalan LibreOffice internal, atau penolakan autentikasi pada 401 atau 403. 401/403 berarti apiKey hilang atau salah. 5xx adalah kegagalan di sisi layanan dan merupakan kandidat untuk percobaan ulang yang dibatasi.

”Content-Type tak terduga dari Gotenberg: (diharapkan application/pdf)”

Pemicu: Statusnya 200, tetapi Content-Type respons tidak memuat application/pdf.
Perbaikan: Ini biasanya berarti sebuah proxy atau gateway mengembalikan halaman galat HTML atau halaman pengalihan dengan 200. Bridge sengaja menonaktifkan pengikutan pengalihan pada transport ber-pin, sehingga respons 3xx tidak diikuti secara diam-diam ke host yang belum diperiksa. Body yang tiba dengan Content-Type yang salah menandakan bahwa ada sesuatu di antara Anda dan Gotenberg yang mengganggu. Periksa jalur jaringan.

”Body respons tidak diawali dengan header %PDF — data PDF tidak valid”

Pemicu: Status 200, Content-Type dapat diterima, tetapi body tidak diawali dengan tanda tangan %PDF.
Perbaikan: Pihak hulu mengembalikan sesuatu yang bukan berkas Portable Document Format (PDF) meskipun header-nya sesuai. Perlakukan respons sebagai tidak tepercaya dan selidiki layanan tersebut. Jangan tulis body ke disk. Bridge menolak mengembalikannya sebagai hasil.

Kegagalan konfigurasi pin

”Format pin SPKI tidak valid: (diharapkan sha256/)”

Tipe: InvalidSpkiPinException
Pemicu: Salah satu string pin yang dikonfigurasi tidak diawali dengan sha256/ atau sha256//.
Perbaikan: Format setiap pin sebagai sha256/<base64-encoded-spki-hash>. Transport juga menerima bentuk asli cURL sha256//<base64>. Hasilkan nilai dari SubjectPublicKeyInfo sertifikat server, bukan dari keseluruhan sertifikat.

”Tertulis tidak tersedia padahal layanan aktif”

isAvailable() mengembalikan false tanpa panggilan jaringan apa pun ketika URL kosong, bukan HTTPS, atau me-resolve ke alamat private/reserved. Metode itu juga mengembalikan false pada galat jaringan apa pun, atau ketika /health mengembalikan 500 atau lebih; dalam kasus tersebut, metode ini menangkap galat alih-alih melemparkannya. Periksa secara berurutan:

URL yang dikonfigurasi tidak kosong dan menggunakan HTTPS.
Host tidak me-resolve ke alamat private/reserved (pelindung SSRF menolaknya bahkan untuk probe).
<apiUrl>/health dapat dijangkau dari host aplikasi dan mengembalikan status di bawah 500.

Lihat juga

/integrations/gotenberg/configuration/ — semua opsi dan aturan pemilihan transport.
/integrations/gotenberg/production-usage/ — kebijakan percobaan ulang dan kontrak penanganan kegagalan.
/integrations/gotenberg/security-and-operations/ — model SSRF dan rotasi pin.
/integrations/gotenberg/quickstart/ — urutan catch lengkap dalam konteks.