NextPDF Gotenberg sorun giderme rehberi

Bir bakışta

Köprü, hataları açıkça ve erkenden bildirir. Her hata, nedenini belirten bir mesajla birlikte türü belirli bir istisna fırlatır. Bu sayfayı bir katalog olarak kullanın. Her hata için istisna türünü, karşılaşacağınız mesaj parçasını, kod yolundaki kesin tetikleyiciyi ve düzeltmeyi bulursunuz.

İstisna aileleri şunlardır:

• GotenbergConvertException — dönüştürme katmanı hatası (yapılandırma, taşıma veya yanıt).
• RuntimeException — güvenlik politikası tarafından herhangi bir ağ trafiği başlamadan önce fırlatılan bir doğrulama katmanı hatası.
• ValueError — tanınmayan bir dosya uzantısı.
• InvalidSpkiPinException — hatalı biçimlendirilmiş bir Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) sabitleme dizesi.

Yapılandırma hataları

”Invalid Gotenberg configuration: apiUrl is empty”

• Tür: GotenbergConvertException
• Tetikleyici: convertFile() veya convertString() çağrısını, GotenbergConfig::isValid() false iken yaptınız. Bu durum, apiUrl boş bir dize olduğunda gerçekleşir.
• Düzeltme: Boş olmayan bir HTTPS URL’si sağlayın. Yapılandırmayı fromArray() ile oluşturuyorsanız, sessizce '' değerinin, eksik veya dize olmayan bir api_url yerine kullanıldığını unutmayın. Yapılandırma kaynağınızı önyükleme sırasında doğrulayın.

URL ve adres (SSRF) hataları

Bu hatalar, sunucu tarafı istek sahteciliğine (SSRF) karşı koruma sağlayan güvenlik politikasından gelir. Köprü, bunları herhangi bir istek göndermeden önce fırlatır. Her biri düz bir RuntimeException hatasıdır.

”Gotenberg API URL must use HTTPS (got: http)”

• Tetikleyici: Yapılandırılan URL şeması https değil. Denetim büyük/küçük harfe duyarsızdır, bu nedenle HTTPS:// kabul edilir.
• Düzeltme: Gotenberg’i TLS arkasına yerleştirin ve HTTPS uç noktasını yapılandırın. Yerel geliştirme için bile düz HTTP reddedilir.

”Invalid Gotenberg API URL: unable to parse”

• Tetikleyici: URL, şema ve ana bilgisayar olarak ayrıştırılamıyor.
• Düzeltme: Söz dizimsel olarak geçerli, mutlak bir URL sağlayın; örneğin https://gotenberg.example.com:3000.

”Gotenberg API URL must not resolve to a private or reserved IP address” (ana bilgisayar özel veya ayrılmış bir adrese çözümleniyor)

• Tetikleyici: Ana bilgisayar, özel veya ayrılmış bir İnternet Protokolü (IP) sabit değeri ya da (tüm A/AAAA kayıtları üzerinden) herhangi bir özel veya ayrılmış adrese çözümlenen bir ana bilgisayar adıdır. Bu, Request for Comments (RFC) 1918 özel aralıklarını, geri döngü (loopback) ve bağlantı yerel (link-local) adresleri engeller.
• Düzeltme: Köprüyü yönlendirilebilir bir genel adrese veya düzgün şekilde bölümlenmiş bir hizmet adresine yönlendirin. Gotenberg örneğiniz bilinçli olarak özel bir ağdaysa, köprünün SSRF koruması bunu tasarım gereği reddeder. Gotenberg’i, korumanın kabul ettiği bir adres üzerinden açığa çıkarın, ardından bu yolu ağ denetimleri ve kimlik doğrulamasıyla koruyun. /integrations/gotenberg/security-and-operations/. sayfasına bakın.

”Gotenberg API URL DNS answer changed since validation — possible DNS rebinding attack”

• Tetikleyici: İlk doğrulama ile istek arasında, yeni bir Etki Alanı Adı Sistemi (DNS) çözümlemesi başlangıçta doğrulanan kümede bulunmayan bir adres döndürdü.
• Düzeltme: Bu, time-of-check/time-of-use korumasının devreye girmesidir. Ana bilgisayarın DNS’ini araştırın. Geçerli bir neden, adresleri dönüşümlü veren bir yük dengeleyici olabilir. Kötü amaçlı bir neden ise yeniden bağlama (rebinding) saldırısıdır. Gotenberg uç noktası için kararlı bir adres ya da kararlı bir kayıt kümesine sahip bir ad kullanın.

Girdi doğrulama hataları

Güvenlik politikası bu hataları istek gönderilmeden önce fırlatır. Aksi belirtilmedikçe her biri düz bir RuntimeException hatasıdır.

”File not found or not readable: ” (dosya bulunamadı ya da okunabilir bir dosya değil)

• Tür: GotenbergConvertException
• Tetikleyici: convertFile() yolu standart biçime getiremedi ya da çözümlenen yol normal, okunabilir bir dosya değil. Bir dizin de bunu tetikler.
• Düzeltme: Var olan ve okunabilir bir dosyaya giden yol geçirin. Yol önce realpath() ile standart biçime getirilir; bu, dizin geçişini (traversal) de engeller.

”File size ( bytes) exceeds maximum allowed size ( bytes)”

• Tetikleyici: Girdi, maxFileSize değerinden büyük (varsayılan 52,428,800 bayt = 50 MiB).
• Düzeltme: Belge gerçekten gerektiriyorsa maxFileSize değerini yükseltin ya da yüklemeyi üst katmanda reddedin. Sınırı, gerçek belgelerinizin izin verdiği ölçüde düşük tutun. Bu, köprünün tek yerleşik kaynak sınırıdır.

Dosya adı reddetmeleri

Köprü, dosya adını doğrular. Dosya dönüştürmelerinde dosya adı, çözümlenen yolun temel adıdır; convertString() için ise geçirdiğiniz addır. Bunların her biri bir RuntimeException hatasıdır:

Mesaj parçası	Tetikleyici
must not be empty	boş dosya adı
path traversal sequences (..)	ad şunu içeriyor: ..
forward slashes	ad şunu içeriyor: /
backslashes	ad şunu içeriyor: \
null bytes	ad bir NUL baytı içeriyor
control characters	ad bir ASCII denetim karakteri (0–31) içeriyor

• Düzeltme: Temiz bir temel ad geçirin. convertString() için report.docx gibi düz bir ad verin. Bu ad, biçim algılama ve çok parçalı yüklemede dosya adı olarak kullanılır; yol olarak kullanılmaz.

”Unknown office format extension: ”

• Tür: ValueError
• Tetikleyici: Dosya uzantısı şunlardan biri değil: docx, xlsx, pptx, odt, ods, odp (büyük/küçük harfe duyarsız, başındaki noktaya izin verilir).
• Düzeltme: Yalnızca tanınan altı biçimi dönüştürün. Köprü, eski ikili biçimleri (.doc, .xls, .ppt), .rtf, .csv, düz metni veya görüntüleri tanımaz. Bu girdileri, köprüyü çağırmadan önce tanınan bir biçime dönüştürün ya da farklı bir yol üzerinden yönlendirin.

Taşıma ve yanıt hataları

Bunların hepsi GotenbergConvertException hatalarıdır.

”Gotenberg HTTP request failed: ”

• Tetikleyici: PHP Standard Recommendation 18 (PSR-18) istemcisi (veya cURL ile sabitlenmiş taşıma) isteği gönderirken bir istisna fırlattı. Nedeni bağlantı reddi, zaman aşımı, TLS el sıkışma hatası ya da sabitleme uyuşmazlığı olabilir.
• İstisna kodu: temel istemci istisnasının kodu.
• Neden: özgün PSR-18 istemci istisnası, önceki istisna olarak eklenir.
• Düzeltme: Şu dört noktayı denetleyin. Hizmetin erişilebilirliğini isAvailable() ile denetleyin. Ağ yolunu denetleyin. TLS zincirini denetleyin. Sabitleme yapılandırılmışsa, sunucunun geçerli SubjectPublicKeyInfo (SPKI) değerinin, yapılandırılmış bir sabitlemeyle eşleştiğini denetleyin. Bir sertifika döndürmesinden sonra oluşan sabitleme uyuşmazlığı, klasik nedendir. Döndürme yordamı için /integrations/gotenberg/security-and-operations/. sayfasına bakın.

”cURL transport error (): ”

• Tetikleyici: cURL ile sabitlenmiş taşımanın curl_exec çağrısı, sıfır olmayan bir cURL hata numarasıyla başarısız oldu ya da dize olmayan bir gövde döndürdü.
• Düzeltme: cURL hata numarası nedeni gösterir (TLS, çözümleme, zaman aşımı, sabitleme). Sabitleme hatası, CURLOPT_PINNEDPUBLICKEY sertifikayı reddettiğinde burada ortaya çıkar. Yapılandırılmış sabitlemelerin ve çözümlenen adresin güncel olduğunu doğrulayın.

”Gotenberg conversion failed with HTTP : ”

• Tetikleyici: Yanıt durumu 200 değildi. Gövde dahil edilir, ilk 500 karaktere kesilir ve daha uzunsa sonuna üç nokta eklenir.
• Düzeltme: Dahil edilen gövdeyi okuyun. Gotenberg’in hata mesajı, dönüştürmenin neden reddedildiğini açıklar: desteklenmeyen belge içeriği, dahili bir LibreOffice hatası ya da 401 veya 403 durumunda kimlik doğrulama reddi. Bir 401/403, apiKey değerinin eksik veya yanlış olduğu anlamına gelir. Bir 5xx, hizmet taraflı bir hatadır ve sınırlı bir yeniden deneme için adaydır.

”Unexpected Content-Type from Gotenberg: (expected application/pdf)”

• Tetikleyici: Durum 200 idi, ancak yanıttaki Content-Type değeri application/pdf içermiyordu.
• Düzeltme: Bu genellikle bir vekil sunucu ya da ağ geçidinin, bir HTML hata veya yönlendirme sayfasını 200 ile döndürdüğü anlamına gelir. Köprü, sabitlenmiş taşımada yönlendirme izlemeyi bilinçli olarak devre dışı bırakır; böylece bir 3xx yanıtı, denetlenmemiş bir ana bilgisayara sessizce izlenmez. Yanlış Content-Type ile gelen bir gövde, sizinle Gotenberg arasında bir şeyin araya girdiğini gösterir. Ağ yolunu inceleyin.

”Response body does not start with %PDF header — invalid PDF data” (yanıt gövdesi %PDF üst bilgisiyle başlamıyor — geçersiz PDF verisi)

• Tetikleyici: Durum 200, Content-Type kabul edilebilir, ancak gövde %PDF imzasıyla başlamıyor.
• Düzeltme: Üst katman, başlıklara rağmen Taşınabilir Belge Biçimi (PDF) dosyası olmayan bir şey döndürdü. Yanıtı güvenilmez olarak ele alın ve hizmeti araştırın. Gövdeyi diske yazmayın. Köprü, onu sonuç olarak döndürmeyi reddeder.

Sabitleme yapılandırma hataları

”Invalid SPKI pin format: (expected sha256/)”

• Tür: InvalidSpkiPinException
• Tetikleyici: Yapılandırılmış bir sabitleme dizesi sha256/ veya sha256// ile başlamıyor.
• Düzeltme: Her sabitlemeyi sha256/<base64-encoded-spki-hash> olarak biçimlendirin. Taşıma, cURL’ye özgü sha256//<base64> biçimini de kabul eder. Değeri, tüm sertifikadan değil, sunucu sertifikasının SubjectPublicKeyInfo bölümünden üretin.

”Hizmet çalışıyor ama kullanılamaz diyor”

isAvailable(), URL boş olduğunda, HTTPS olmadığında ya da private/reserved (özel/ayrılmış) bir adrese çözümlendiğinde herhangi bir ağ çağrısı yapmadan false döndürür. Ayrıca false değerini, herhangi bir ağ hatasında ya da /health 500 veya üzeri döndürdüğünde de döndürür; bu durumlarda hata fırlatmak yerine hatayı yakalar. Sırayla denetleyin:

1. Yapılandırılan URL’nin boş olmadığını ve HTTPS olduğunu doğrulayın.
2. Ana bilgisayarın private/reserved bir adrese çözümlenmediğini doğrulayın (SSRF koruması, sınama için bile bunu reddeder).
3. <apiUrl>/health uç noktasının uygulama ana bilgisayarından erişilebilir olduğunu ve 500 altında bir durum döndürdüğünü doğrulayın.

Ayrıca bakın

• /integrations/gotenberg/configuration/ — tüm seçenekler ve taşıma seçim kuralları.
• /integrations/gotenberg/production-usage/ — yeniden deneme politikası ve hata işleme sözleşmesi.
• /integrations/gotenberg/security-and-operations/ — SSRF modeli ve sabitleme döndürmesi.
• /integrations/gotenberg/quickstart/ — bağlam içindeki ayrıntılı yakalama sırası.