Skip to main content

Troubleshooting

Issue not listed here? Check GitHub issues and discussions, or open a new one.

API​

Bad Request (400)​

A 400 Bad Request means the form data failed validation: a missing required form field, a malformed JSON value, an unsupported file extension, or an invalid field value. The body is plain text naming the offending field:

Invalid form data: a 'userPassword' or 'ownerPassword' is required

Match the Gotenberg-Trace response header against the logs for full context.

Chromium​

Blank or Missing Content​

  • Dynamic Content: If your page relies on JavaScript to render, Chromium might print before it finishes. Use waitDelay or waitForExpression to pause the conversion until the page is ready.
  • Backgrounds: By default, browsers remove backgrounds for printing. Enable the printBackground form field, or use the CSS property -webkit-print-color-adjust: exact;.
  • Network Idle: For versions after 8.11.0, try setting the skipNetworkIdleEvent form field to false.
  • Updates: Consider upgrading to the latest Gotenberg version to benefit from debugging features like Network Errors or Invalid HTTP Status Codes.

Blank Charts or Empty Google Maps​

Charting libraries (@visx/responsive, ApexCharts) and Google Maps rendered as empty rectangles between 8.29.0 and 8.31.0.

The chromedp 0.15.0 print pipeline suspended requestAnimationFrame, ResizeObserver, IntersectionObserver, and CSS transitionend / animationend between the load event and Page.printToPDF. Libraries measuring their container inside an rAF callback never received a frame.

Fixed in 8.32.0 by pinning chromedp back to v0.14.2. Upgrade to 8.32.0 or later (issues #1531, #1534, #1535).

Sub-Resources Stopped Loading After 8.31.0​

8.31.0 blocked Chromium sub-resources resolving to private IPs by default. CSS, images, and iframes hosted on internal hostnames stopped loading.

8.32.0 restores permissive defaults. Private-IP sub-resources load again without configuration.

Set CHROMIUM_DENY_PRIVATE_IPS=true to keep the strict 8.31.0-style posture. See Outbound URL Filtering.

Localhost / Missing Assets​

  • Container Networking: The Gotenberg container has its own network. If you try to convert http://localhost:3000, it looks inside the container, not your host machine. Use your host's actual network IP, or Docker's DNS (e.g., host.docker.internal).
  • Unresolved Assets: Ensure all CSS, fonts, and images are either accessible from the internet, sent as additional files in your multipart request, or embedded as Base64.

Large PDFs​

Fails to Start​

Liveness Probe Failures Under Load​

Before 8.33.0, a single slow health probe under heavy load flipped /health to unhealthy, causing Kubernetes liveness probes to restart otherwise healthy pods.

Since 8.33.0, Gotenberg tolerates one transient probe failure and briefly caches successful probe results, so probe spam no longer piles onto a busy engine (Issue #1561). The same applies to LibreOffice probes. A genuinely dead process still surfaces on the next probe.

Print Error (-32000)​

  • This error often occurs when converting massive documents. Increasing container memory might help, but note that it is a known Chromium bug (Issue #788).
  • Unusually large headers or footers injected via the API can also trigger this error.

Clipped Screenshots​

  • If your screenshots are repeating or clipped, set the skipNetworkIdleEvent form field to false (Issue #1065).

Timeouts (503)​

  • Overload: Check if your Gotenberg instance is overwhelmed. Scale horizontally by adding more instances if needed.
  • Accessibility: Ensure the target page’s resources respond quickly.
  • Configuration: Increase the API timeout (API module configuration). Optionally, define a maximum queue size for faster request aborts (Chromium module configuration).

LibreOffice​

Layout & Font Shifts​

  • Missing Fonts: LibreOffice relies on installed system fonts to calculate page breaks and layout. If your document uses a font not present in the container, LibreOffice will substitute it, causing shifted layouts. Install the required fonts via a custom Dockerfile (see Fonts configuration).
  • After upgrading to 8.30.0: The font stack was simplified from 30+ packages to 8. Documents relying on Microsoft Core Fonts (Arial, Times New Roman, Calibri) now use metric-compatible replacements. If you notice layout differences after upgrading, install ttf-mscorefonts-installer or the specific script fonts your documents need (see Fonts configuration).
  • Clipped Form Field Text: When form fields reference fonts that aren't embedded, LibreOffice sizes the widget boxes with a fallback font, making them too small and clipping the text. Set exportFormFields=false to flatten the fields and remove the mismatch (see Native Flattening).

Linked Images Missing After 8.34.0​

8.34.0 blocks content linked from untrusted locations, and uploaded documents always count as untrusted. The conversion succeeds with 200 OK; linked images and other linked content are absent.

Embed content in the document instead of linking it. There is no opt-out: the block closes a local-file-read and SSRF vector. See Outbound URL Filtering.

Server Errors (500)​

  • Resource Limits: Office document conversion is resource-heavy. Try increasing Gotenberg’s memory and CPU allocations (Issue #465).
  • Retrying: A 500 from /forms/libreoffice/convert means no form field explains the failure, so the request is valid and worth retrying. A 400 names the field to correct and fails the same way on every attempt. See Deciding Whether to Retry.

UUID Printed in CSV Page Headers​

Before 8.34.0, converting a .csv file printed a random UUID as a centered page header. LibreOffice names the Calc sheet after the input file, which Gotenberg stores under a UUID-based filename, and the default page style prints that sheet name as a header.

Fixed in 8.34.0: Gotenberg suppresses the auto-generated header for CSV inputs. Spreadsheets with their own page styles (.xlsx, .ods) are unaffected (Issue #1568).

Fails to Start​

First Request Times Out, Subsequent Requests Fail Until Container Restart​

Before 8.32.0, the supervisor cached a failed first launch and returned the same error to every subsequent request. This happened when LIBREOFFICE_START_TIMEOUT was shorter than soffice's cold start.

Fixed in 8.32.0. A failed launch leaves state clean and the next request retries from scratch (Issue #1538).

For older versions, increase LIBREOFFICE_START_TIMEOUT (default 20s) to comfortably exceed soffice cold-start time.

PDF/A-1a Support​

  • Starting with version 7.6, LibreOffice no longer supports PDF/A-1a. It previously generated PDF/A-1b files anyway, though some validators misidentified them (LibreOffice commit).

Tables Rasterized to Images with PDF/A or PDF/UA​

LibreOffice rasterizes table cells that carry a background color when it re-processes a document for PDF/A or PDF/UA. The resulting images have no alt text, so the output is less accessible than the source (Issue #1292).

Removing the background color keeps the table as text. On Chromium routes, generateTaggedPdf embeds a structure tree during generation without the LibreOffice pass (Native Accessibility). For strict PDF/A compliance, convert with an external tool such as Ghostscript.

Timeouts (503)​

Webhooks​

HTTPS Webhooks Fail in the Chromium Variant​

Before 8.34.0, the gotenberg/gotenberg:8-chromium image variant shipped without ca-certificates, so webhook calls to HTTPS endpoints failed TLS certificate verification. Conversions themselves were unaffected: Chromium bundles its own certificates.

Fixed in 8.34.0; the full and LibreOffice variants were never affected. For older versions, install ca-certificates in a custom Dockerfile.

What's Next?​

Still stuck? Ask the community on GitHub Discussions, or open an issue.