Skip to main content

Troubleshooting

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

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 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​

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 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).

Server Errors (500)​

  • Resource Limits: Office document conversion is resource-heavy. Try increasing Gotenberg’s memory and CPU allocations (Issue #465).

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).

Timeouts (503)​

Sponsors
TheCodingMachinepdfmePdfBolt
Powered by
DockerJetBrains
❤️ Become a sponsor