Skip to main content

Troubleshooting

If you encounter an issue not covered here, please:

  1. Check if it's already been reported on the GitHub issues or GitHub discussions.
  2. Open a new issue or start a discussion if needed.

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.

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. You must install the required fonts via a custom Dockerfile (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​

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

SponsorsTCMpdfme
Powered byDockerJetBrains
❤️ Become a sponsor