NextPDF Gotenberg – Fehlerbehebung

Auf einen Blick

Die Bridge schlägt früh und deutlich fehl. Jeder Fehler ist eine typisierte Ausnahme; die Meldung benennt die Ursache. Diese Seite dient als Katalog. Zu jedem Fehler nennt sie den Ausnahmetyp, das erwartete Meldungsfragment, den genauen Auslöser im Codepfad und die Behebung.

Die Ausnahmefamilien sind:

• GotenbergConvertException – Fehler in der Konvertierungsschicht (Konfiguration, Transport oder Antwort).
• RuntimeException – Fehler in der Validierungsschicht, ausgelöst durch die Sicherheitsrichtlinie, noch vor jeglichem Netzwerkverkehr.
• ValueError – eine unbekannte Dateierweiterung.
• InvalidSpkiPinException – ein falsch formatierter TLS-Pin-String.

Konfigurationsfehler

”Invalid Gotenberg configuration: apiUrl is empty”

• Typ: GotenbergConvertException
• Auslöser: convertFile() oder convertString() wurde aufgerufen, wenn GotenbergConfig::isValid() false zurückgibt. Das passiert, wenn apiUrl eine leere Zeichenkette ist.
• Behebung: Geben Sie eine nicht leere HTTPS-URL an. Wenn Sie die Konfiguration mit fromArray() erstellen, beachten Sie, dass für eine fehlende oder nicht als String vorliegende api_url stillschweigend '' eingesetzt wird. Validieren Sie Ihre Konfigurationsquelle in Ihrem Bootpfad.

URL- und Adressfehler (SSRF)

Diese Fehler stammen von der Sicherheitsrichtlinie, die vor Server-Side Request Forgery (SSRF) schützt. Sie werden vor dem Senden einer Anfrage ausgelöst. Es handelt sich jeweils um eine einfache RuntimeException.

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

• Auslöser: Das konfigurierte URL-Schema ist nicht https. Die Prüfung erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung, sodass HTTPS:// akzeptiert wird.
• Behebung: Schalten Sie TLS vor Gotenberg und konfigurieren Sie den HTTPS-Endpunkt. Einfaches HTTP wird selbst für die lokale Entwicklung abgelehnt.

”Invalid Gotenberg API URL: unable to parse”

• Auslöser: Die URL kann nicht in Schema und Host zerlegt werden.
• Behebung: Geben Sie eine syntaktisch gültige absolute URL an, zum Beispiel https://gotenberg.example.com:3000.

”Gotenberg API URL must not resolve to a private or reserved IP address”

• Auslöser: Der Host ist ein privates oder reserviertes IP-Literal oder ein Hostname, der (über alle A-/AAAA-Einträge) zu einer privaten oder reservierten Adresse auflöst. Dies blockiert RFC 1918-Bereiche, Loopback- und Link-Local-Adressen.
• Behebung: Richten Sie die Bridge auf eine routbare öffentliche oder ordnungsgemäß segmentierte Dienstadresse aus. Wenn sich Ihr Gotenberg absichtlich in einem privaten Netzwerk befindet, lehnt der SSRF-Schutz der Bridge ihn per Design ab. Stellen Sie ihn über eine Adresse bereit, die der Schutz akzeptiert, und sichern Sie diesen Pfad stattdessen mit Netzwerkkontrollen und Authentifizierung. Siehe /integrations/gotenberg/security-and-operations/.

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

• Auslöser: Zwischen der ersten Validierung und der Anfrage hat eine erneute DNS-Auflösung eine Adresse zurückgegeben, die nicht im ursprünglich validierten Satz enthalten war.
• Behebung: Hier greift der time-of-check/time-of-use-Schutz. Prüfen Sie die DNS-Konfiguration für den Host. Eine legitime Ursache ist ein Load Balancer, der Adressen rotiert. Eine bösartige Ursache ist ein Rebinding-Angriff. Verwenden Sie für den Gotenberg-Endpunkt eine stabile Adresse oder einen Namen mit einem stabilen Eintragssatz.

Eingabevalidierungsfehler

Diese Fehler werden von der Sicherheitsrichtlinie vor der Anfrage ausgelöst. Jeder ist eine einfache RuntimeException, sofern nicht anders angegeben.

”File not found or not readable: ”

• Typ: GotenbergConvertException
• Auslöser: convertFile() konnte den Pfad nicht kanonisieren, oder der aufgelöste Pfad ist keine reguläre, lesbare Datei. Auch ein Verzeichnis löst dies aus.
• Behebung: Übergeben Sie einen Pfad zu einer vorhandenen, lesbaren Datei. Der Pfad wird zuerst mit realpath() kanonisiert, was zugleich Traversal abwehrt.

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

• Auslöser: Die Eingabe ist größer als maxFileSize (Standard 52.428.800 Bytes = 50 MiB).
• Behebung: Erhöhen Sie maxFileSize, wenn das Dokument diese Größe tatsächlich benötigt, oder lehnen Sie den Upload vorgelagert ab. Halten Sie die Obergrenze so niedrig, wie es Ihre tatsächlichen Dokumente zulassen. Sie ist die einzige eingebaute Ressourcengrenze der Bridge.

Ablehnungen von Dateinamen

Der Dateiname wird überprüft. Bei Dateikonvertierungen ist der Dateiname der Basisname des aufgelösten Pfads; bei convertString() ist es der von Ihnen übergebene Name. Jeder dieser Befunde führt zu einer RuntimeException:

Meldungsfragment	Auslöser
must not be empty	leerer Dateiname
path traversal sequences (..)	Der Name enthält ..
forward slashes	Der Name enthält /
backslashes	Der Name enthält \
null bytes	Der Name enthält ein NUL-Byte
control characters	Der Name enthält ein ASCII-Steuerzeichen (0–31)

• Behebung: Übergeben Sie einen sauberen Basisnamen. Für convertString() geben Sie einen einfachen Namen wie report.docx an. Er wird für die Formaterkennung und als Dateiname des Multipart-Uploads verwendet, nicht als Pfad.

”Unknown office format extension: ”

• Typ: ValueError
• Auslöser: Die Dateierweiterung gehört nicht zu docx, xlsx, pptx, odt, ods, odp (ohne Berücksichtigung der Groß-/Kleinschreibung, ein führender Punkt wird toleriert).
• Behebung: Konvertieren Sie nur die sechs erkannten Formate. Die Bridge erkennt die älteren Binärformate (.doc, .xls, .ppt), .rtf, .csv, reinen Text oder Bilder nicht. Konvertieren Sie diese Eingaben in ein erkanntes Format, bevor Sie die Bridge aufrufen, oder verarbeiten Sie sie über einen anderen Pfad.

Transport- und Antwortfehler

Alle diese sind GotenbergConvertException.

”Gotenberg HTTP request failed: ”

• Auslöser: Der PSR-18-Client (oder der cURL-Pinned-Transport) hat beim Senden der Anfrage eine Ausnahme ausgelöst. Die Ursache ist eine abgelehnte Verbindung, ein Timeout, ein Fehler beim TLS-Handshake oder eine Pin-Abweichung.
• Ausnahmecode: der Code der zugrunde liegenden Client-Ausnahme.
• Ursache: Die ursprüngliche PSR-18-Client-Ausnahme ist als vorherige Ausnahme angehängt.
• Behebung: Prüfen Sie vier Punkte: die Erreichbarkeit des Dienstes mit isAvailable(), den Netzwerkpfad, die TLS-Kette und, falls Pinning konfiguriert ist, ob die aktuelle SubjectPublicKeyInfo (SPKI) des Servers mit einem konfigurierten Pin übereinstimmt. Eine Pin-Abweichung nach einer Zertifikatsrotation ist die klassische Ursache. Das Rotationsverfahren finden Sie unter /integrations/gotenberg/security-and-operations/.

“cURL transport error (): ”

• Auslöser: Der Aufruf von curl_exec im cURL-Pinned-Transport ist mit einer cURL-Fehlernummer ungleich null fehlgeschlagen oder hat einen Körper zurückgegeben, der kein String ist.
• Behebung: Die cURL-Fehlernummer identifiziert die Ursache (TLS, Auflösung, Timeout, Pin). Ein Pinning-Fehler wird hier sichtbar, wenn CURLOPT_PINNEDPUBLICKEY das Zertifikat ablehnt. Bestätigen Sie, dass die konfigurierten Pins und die aufgelöste Adresse aktuell sind.

”Gotenberg conversion failed with HTTP : ”

• Auslöser: Der Antwortstatus war nicht 200. Der Körper wird einbezogen und auf die ersten 500 Zeichen gekürzt; ist er länger, wird eine Auslassung angehängt.
• Behebung: Lesen Sie den einbezogenen Körper. Die Fehlermeldung von Gotenberg erklärt, warum die Konvertierung abgelehnt wurde: nicht unterstützter Dokumentinhalt, ein interner LibreOffice-Fehler oder eine Authentifizierungsablehnung bei einem 401 oder 403. Ein 401/403 bedeutet, dass der apiKey fehlt oder falsch ist. Ein 5xx ist ein dienstseitiger Fehler und ein Kandidat für einen begrenzten Wiederholungsversuch.

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

• Auslöser: Der Status war 200, aber der Content-Type der Antwort enthielt nicht application/pdf.
• Behebung: Das bedeutet in der Regel, dass ein Proxy oder Gateway eine HTML-Fehler- oder Weiterleitungsseite mit einem 200 zurückgegeben hat. Die Bridge deaktiviert das Folgen von Weiterleitungen auf dem Pinned-Transport bewusst, sodass ein 3xx nicht stillschweigend zu einem ungeprüften Host verfolgt wird. Ein Körper, der mit dem falschen Typ eintrifft, signalisiert, dass etwas zwischen Ihnen und Gotenberg eingreift. Untersuchen Sie den Netzwerkpfad.

”Response body does not start with %PDF header — invalid PDF data”

• Auslöser: Status 200, Content-Type akzeptabel, aber der Körper beginnt nicht mit der %PDF-Signatur.
• Behebung: Der Upstream hat trotz der Header etwas zurückgegeben, das kein PDF ist. Behandeln Sie die Antwort als nicht vertrauenswürdig und untersuchen Sie den Dienst. Schreiben Sie den Körper nicht auf die Festplatte. Die Bridge verweigert die Rückgabe als Ergebnis.

Pin-Konfigurationsfehler

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

• Typ: InvalidSpkiPinException
• Auslöser: Ein konfigurierter Pin-String beginnt weder mit sha256/ noch mit sha256//.
• Behebung: Formatieren Sie jeden Pin als sha256/<base64-encoded-spki-hash>. Der Transport akzeptiert außerdem die cURL-native Form sha256//<base64>. Erzeugen Sie den Wert aus der SubjectPublicKeyInfo des Serverzertifikats, nicht aus dem gesamten Zertifikat.

”It says unavailable but the service is up”

isAvailable() gibt false ohne jeden Netzwerkaufruf zurück, wenn die URL leer ist, kein HTTPS verwendet oder zu einer privaten oder reservierten Adresse auflöst. Sie gibt außerdem false bei jedem Netzwerkfehler zurück oder wenn /health 500 oder höher zurückgibt; in diesen Fällen fängt sie den Fehler ab, anstatt ihn auszulösen. Prüfen Sie der Reihe nach:

1. Die konfigurierte URL ist nicht leer und verwendet HTTPS.
2. Der Host löst nicht zu einer privaten oder reservierten Adresse auf (der SSRF-Schutz lehnt ihn selbst für die Prüfung ab).
3. <apiUrl>/health ist vom Anwendungshost aus erreichbar und gibt einen Status unter 500 zurück.

Siehe auch

• /integrations/gotenberg/configuration/ – jede Option und die Regeln zur Transportauswahl.
• /integrations/gotenberg/production-usage/ – Wiederholungsrichtlinie und Vertrag zur Fehlerbehandlung.
• /integrations/gotenberg/security-and-operations/ – das SSRF-Modell und die Pin-Rotation.
• /integrations/gotenberg/quickstart/ – die vollständige Catch-Reihenfolge im Kontext.