Probleemoplossing voor NextPDF Gotenberg

In het kort

De bridge faalt vroeg en expliciet. Bij elke fout wordt een getypeerde uitzondering geworpen met een bericht dat de oorzaak noemt. Gebruik deze pagina als catalogus. Per fout vindt u het uitzonderingstype, het berichtfragment dat u ziet, de exacte trigger in het codepad en de oplossing.

De uitzonderingsfamilies zijn:

GotenbergConvertException — een fout in de conversielaag (configuratie, transport of respons).
RuntimeException — een fout in de validatielaag, die door het beveiligingsbeleid wordt geworpen vóór enig netwerkverkeer.
ValueError — een niet-herkende bestandsextensie.
InvalidSpkiPinException — een ongeldige Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) pin-tekenreeks.

Configuratiefouten

“Invalid Gotenberg configuration: apiUrl is empty”

Type: GotenbergConvertException
Trigger: U hebt convertFile() of convertString() aangeroepen terwijl GotenbergConfig::isValid() false is. Dit gebeurt wanneer apiUrl een lege tekenreeks bevat.
Fix: Geef een niet-lege HTTPS-URL op. Als u de configuratie opbouwt met fromArray(), houd er dan rekening mee dat die stilzwijgend '' invult voor een ontbrekende of niet-stringwaarde van api_url. Valideer uw configuratiebron tijdens het opstarten.

URL- en adresfouten (SSRF)

Deze fouten komen uit het beveiligingsbeleid, dat beschermt tegen server-side request forgery (SSRF). De bridge werpt ze voordat een verzoek wordt verzonden. Elke fout is een gewone RuntimeException.

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

Trigger: Het geconfigureerde URL-schema is niet https. De controle is niet hoofdlettergevoelig, dus HTTPS:// wordt geaccepteerd.
Fix: Plaats Gotenberg achter TLS en configureer het HTTPS-eindpunt. Gewone HTTP wordt afgewezen, zelfs voor lokale ontwikkeling.

“Invalid Gotenberg API URL: unable to parse”

Trigger: De URL kan niet worden ontleed in een schema en host.
Fix: Geef een syntactisch geldige absolute URL op, bijvoorbeeld https://gotenberg.example.com:3000.

“Gotenberg API URL must not resolve to a private or reserved IP address” (de host wordt herleid naar een privé- of gereserveerd adres)

Trigger: De host is een Internet Protocol (IP)-literal voor een privé- of gereserveerd adres, of een hostnaam die (via alle A/AAAA-records) wordt herleid naar een privé- of gereserveerd adres. Dit blokkeert de privébereiken uit Request for Comments (RFC) 1918, loopback- en link-local-adressen.
Fix: Richt de bridge op een routeerbaar openbaar adres of een correct gesegmenteerd serviceadres. Als uw Gotenberg bewust in een privénetwerk staat, wijst de SSRF-bewaking van de bridge dit per ontwerp af. Stel het beschikbaar via een adres dat de bewaking accepteert en bescherm dat pad vervolgens met netwerkcontroles en authenticatie. Zie /integrations/gotenberg/security-and-operations/.

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

Trigger: Tussen de eerste validatie en het verzoek heeft een nieuwe Domain Name System (DNS)-resolutie een adres geretourneerd dat niet in de oorspronkelijk gevalideerde set zat.
Fix: Dit is de time-of-check/time-of-use-bewaking die wordt getriggerd. Onderzoek de DNS-configuratie van de host. Een geldige oorzaak is een loadbalancer die adressen wisselt. Een kwaadaardige oorzaak is een rebinding-aanval. Gebruik een stabiel adres of een naam met een stabiele recordset voor het Gotenberg-eindpunt.

Invoervalidatiefouten

Het beveiligingsbeleid werpt deze fouten vóór het verzoek wordt verzonden. Elke fout is een gewone RuntimeException, tenzij anders vermeld.

“File not found or not readable: ” (het bestand is niet gevonden of niet leesbaar)

Type: GotenbergConvertException
Trigger: convertFile() kon het pad niet canoniseren, of het gecanoniseerde pad is geen regulier, leesbaar bestand. Een map veroorzaakt dit ook.
Fix: Geef een pad naar een bestaand, leesbaar bestand op. Het pad wordt eerst gecanoniseerd met realpath(), wat ook traversal voorkomt.

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

Trigger: De invoer is groter dan maxFileSize (standaard 52.428.800 bytes = 50 MiB).
Fix: Verhoog maxFileSize als het document dit legitiem nodig heeft, of weiger de upload stroomopwaarts. Houd de limiet zo laag als uw werkelijke documenten toelaten. Dit is de enige ingebouwde resourcelimiet van de bridge.

Afwijzingen van bestandsnamen

De bridge valideert de bestandsnaam. Voor bestandsconversies is de bestandsnaam de basename van het herleide pad; voor convertString() is het de naam die u doorgeeft. Elk van deze afwijzingen is een RuntimeException:

Berichtfragment	Trigger
`must not be empty`	lege bestandsnaam
`path traversal sequences (..)`	de naam bevat `..`
`forward slashes`	de naam bevat `/`
`backslashes`	de naam bevat `\`
`null bytes`	de naam bevat een NUL-byte
`control characters`	de naam bevat een ASCII-controleteken (0–31)

Fix: Geef een schone basename op. Geef voor convertString() een gewone naam op, zoals report.docx. Deze naam wordt gebruikt voor formaatdetectie en als bestandsnaam van de multipart-upload, niet als pad.

“Unknown office format extension: ”

Type: ValueError
Trigger: De bestandsextensie is geen van docx, xlsx, pptx, odt, ods, odp (niet hoofdlettergevoelig, een voorlooppunt wordt getolereerd).
Fix: Converteer alleen de zes herkende formaten. De bridge herkent de oudere binaire formaten (.doc, .xls, .ppt), .rtf, .csv, platte tekst of afbeeldingen niet. Converteer deze invoer naar een herkend formaat voordat u de bridge aanroept, of leid ze via een ander pad.

Transport- en responsfouten

Dit zijn allemaal GotenbergConvertException.

“Gotenberg HTTP request failed: ”

Trigger: De PHP Standard Recommendation 18 (PSR-18)-client (of het cURL-gepinde transport) wierp tijdens het verzenden van het verzoek een uitzondering. De oorzaak is een geweigerde verbinding, een time-out, een mislukte TLS-handshake of een pin-mismatch.
Exception code: de code van de onderliggende clientuitzondering.
Cause: de oorspronkelijke PSR-18-clientuitzondering is gekoppeld als vorige uitzondering.
Fix: Controleer vier zaken: de bereikbaarheid van de service met isAvailable(), het netwerkpad, de TLS-keten en, als pinning is geconfigureerd, of de huidige SubjectPublicKeyInfo (SPKI) van de server overeenkomt met een geconfigureerde pin. Een pin-mismatch na een certificaatrotatie is de typische oorzaak. Zie de rotatieprocedure in /integrations/gotenberg/security-and-operations/.

“cURL transport error (): ”

Trigger: De curl_exec-aanroep van het cURL-gepinde transport mislukte met een cURL-foutnummer dat niet nul is, of retourneerde een body die geen string is.
Fix: Het cURL-foutnummer identificeert de oorzaak (TLS, herleiding, time-out, pin). Een pinning-fout wordt hier zichtbaar wanneer CURLOPT_PINNEDPUBLICKEY het certificaat afwijst. Bevestig dat de geconfigureerde pins en het geresolveerde adres actueel zijn.

“Gotenberg conversion failed with HTTP : ”

Trigger: De responsstatus was niet 200. De body wordt meegestuurd en afgekapt tot de eerste 500 tekens; als die langer is, wordt een beletselteken toegevoegd.
Fix: Lees de meegestuurde body. De foutmelding van Gotenberg legt uit waarom de conversie is afgewezen: niet-ondersteunde documentinhoud, een interne LibreOffice-fout of een authenticatieafwijzing bij een 401 of 403. Een 401/403 betekent dat de apiKey ontbreekt of onjuist is. Een 5xx is een fout aan de servicezijde en komt in aanmerking voor een begrensde nieuwe poging.

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

Trigger: De status was 200, maar de respons-Content-Type bevatte geen application/pdf.
Fix: Dit betekent meestal dat een proxy of gateway een HTML-foutpagina of omleidingspagina retourneerde met een 200. De bridge schakelt het volgen van omleidingen op het gepinde transport bewust uit, zodat een 3xx-respons niet stilzwijgend wordt gevolgd naar een niet-gecontroleerde host. Een body met het verkeerde Content-Type geeft aan dat iets tussen u en Gotenberg interfereert. Inspecteer het netwerkpad.

“Response body does not start with %PDF header — invalid PDF data” (de responsbody begint niet met de %PDF-header)

Trigger: Status 200, Content-Type acceptabel, maar de body begint niet met de %PDF-signatuur.
Fix: De upstream retourneerde iets dat geen Portable Document Format (PDF)-bestand is, ondanks de headers. Behandel de respons als onbetrouwbaar en onderzoek de service. Schrijf de body niet naar schijf. De bridge weigert die als resultaat te retourneren.

Pinconfiguratiefouten

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

Type: InvalidSpkiPinException
Trigger: Een geconfigureerde pin-tekenreeks begint niet met sha256/ of sha256//.
Fix: Formatteer elke pin als sha256/<base64-encoded-spki-hash>. Het transport accepteert ook de cURL-eigen vorm sha256//<base64>. Genereer de waarde uit de SubjectPublicKeyInfo van het servercertificaat, niet uit het hele certificaat.

“It says unavailable but the service is up”

isAvailable() retourneert false zonder enige netwerkaanroep wanneer de URL leeg is, niet HTTPS is, of wordt herleid naar een privé- of gereserveerd adres. Het retourneert ook false bij elke netwerkfout of wanneer /health 500 of hoger retourneert; in die gevallen vangt het de fout af in plaats van die te werpen. Controleer, op volgorde:

De geconfigureerde URL is niet leeg en gebruikt HTTPS.
De host wordt niet herleid naar een privé- of gereserveerd adres (de SSRF-bewaking wijst dit zelfs voor de probe af).
<apiUrl>/health is bereikbaar vanaf de applicatiehost en retourneert een status onder 500.

Zie ook

/integrations/gotenberg/configuration/ — alle opties en regels voor transportselectie.
/integrations/gotenberg/production-usage/ — het beleid voor nieuwe pogingen en het contract voor foutafhandeling.
/integrations/gotenberg/security-and-operations/ — het SSRF-model en pin-rotatie.
/integrations/gotenberg/quickstart/ — de uitputtende catch-volgorde in context.