Errors
An error answers with a status and a plain-text message that says what failed and how to fix it:
curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--form url=https://example.com \
--form paperSize=A9
Response
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=UTF-8
Invalid form data: form field 'paperSize' is invalid (got 'A9', want A3, A4, A5, B4, B5, Letter, Legal or Tabloid)
With a webhook, the error reaches the events URL instead: see Webhook requests.
Status codes
| Status | Meaning |
|---|---|
| 400 | A form field, a stage or a header is missing or invalid, or a stage failed on a file. The message names it. |
| 401 | The credentials are missing or wrong, with authentication on. |
| 403 | The outbound URL filtering blocks a URL: the page Chromium loads, a downloadFrom file, a webhook or a timestamp authority. The message stays generic; Gotenberg's logs say why. A host that doesn't resolve answers 400 instead, naming it, except a timestamp authority's. |
| 404 | The route doesn't exist, or its engine isn't in this image variant. The message names the path. |
| 409 | The page Chromium loaded answered an error status, 4xx or 5xx by default, or failed another failOn check. |
| 413 | The request is larger than --api-body-limit allows. |
| 405 | The route doesn't take the method you sent. The message names it and lists the ones the route takes. |
| 415 | The request isn't multipart/form-data. |
| 429 | The Chromium or LibreOffice queue is full: see --chromium-max-queue-size. Retry shortly. |
| 503 | The request took longer than --api-timeout, 30 seconds by default, a Chromium wait included, or Chromium crashed. Retry. |
| 500 | Something else failed, such as an engine crash. Look the request's Gotenberg-Trace up in Gotenberg's logs. |
Messages
A form field names itself, the value you sent, and what it wants:
Invalid form data: form field 'url' is required
Invalid form data: form field 'paperSize' is invalid (got 'A9', want A3, A4, A5, B4, B5, Letter, Legal or Tabloid)
Invalid form data: form field 'landscape' is invalid (got 'foo', want true or false)
A field the route doesn't read answers 400 too. A Gotenberg 8 field says where it went:
Invalid form data: form field 'merge' is unknown to this route; Gotenberg 9 moved it to a stage: add {"op":"merge"} to 'stages'
A URL whose host doesn't resolve names the host:
Invalid form data: form field 'url' is invalid: the host 'nope.invalid' does not resolve
Invalid 'Gotenberg-Webhook-Url' header: the host 'storage.example.invalid' does not resolve
Invalid form data: form field 'downloadFrom' entry 0 is invalid (the host 'nonexistent.invalid' does not resolve)
A URL that isn't absolute, with an http or https scheme and a host, names the header or the entry, and shows one that works. Each webhook header needs the other:
Invalid 'Gotenberg-Webhook-Url' header: want an absolute URL with an http or https scheme and a host, such as https://example.com/upload
Invalid form data: form field 'downloadFrom' entry 1 is invalid (want an absolute URL with an http or https scheme and a host, such as https://example.com/file.pdf)
The 'Gotenberg-Webhook-Url' header is required with 'Gotenberg-Webhook-Events-Url'
A download whose server sends no file name says what to send:
Unable to download file from 'https://example.com/': the response has no 'Content-Disposition' header. Make the server send one with a filename, such as 'attachment; filename="file.pdf"'
A route or a method Gotenberg doesn't serve names it:
The route '/nope' does not exist. Check the path, and that this image includes the module that serves it
The route '/forms/pdf/merge' does not accept the GET method. Use one of: OPTIONS, POST
A list of stages names the stage, counted from 0, and the rule it breaks:
Invalid form data: form field 'stages' is invalid: stage 0: rotate: "angle" is invalid (got "x", want an integer)
Invalid form data: form field 'stages' is invalid: stage 0: rotate: "angle" must be a multiple of 90, got 45
Invalid form data: form field 'stages' is invalid: stage 1: "rotate" cannot follow "encrypt": only optimize and render may
An unknown operation lists the ones Gotenberg runs, and an option out of range says what it takes:
Invalid form data: form field 'stages' is invalid: stage 0: unknown operation "nope"; the operations are attach, autotag, convert-colors, decrypt, delete, detach, encrypt, flatten-form, flatten-transparency, insert, merge, optimize, redact, remediate, render, rotate, select, set-bookmarks, set-form, set-metadata, sign, split, stamp-image, stamp-pdf, stamp-text, timestamp
Invalid form data: form field 'stages' is invalid: stage 0: render: "dpi" must be at least 1, got 0
A stage that fails on a file names both. A file that isn't a PDF, or a truncated or corrupt one, fails the same way on every PDF route:
Stage 'select' failed on 'report.pdf': invalid page range: page 9 out of range [1, 3]
Stage 'decrypt' failed on 'encrypted.pdf': the PDF is encrypted, and the 'password' is missing or wrong
Stage 'info' failed on 'report.pdf': not a valid PDF document: trailer missing /Root