Skip to main content
Version: 8.x

Troubleshooting

This page comprises a selection of frequently encountered problems and their corresponding solutions associated with Gotenberg. Given the wide array of tools integrated within Gotenberg, it can sometimes be challenging to pinpoint the root of an issue.

However, should you encounter an issue not addressed here, kindly take the following steps:

  1. Verify whether your issue has already been discussed or identified within the GitHub issues or the GitHub discussions.
  2. If it hasn't been addressed, feel free to open a new issue or initiate a discussion, based on the nature of your predicament.

Chromium​

Gotenberg internally employs the same protocol as Puppeteer for communication with Chromium. Therefore, it may be useful to include "puppeteer" as a keyword when searching for solutions to your issue. More often than not, you're likely to find an answer to your problem.

Oversized PDF Files​

The usage of webfonts tends to considerably enlarge the PDF file size. If you wish to use a custom font, please refer to the fonts configuration section to learn how to install them directly into the Docker container.

For additional details, see issue #521.

Trouble Starting​

Startup failures can happen due to several factors. Here are some known solutions:

  • Increase the start timeout. See the Chromium module configuration for guidance.
  • If you're using macOS, consider disabling the Use Virtualization Framework feature. For additional details, see issue #792.

Printing Failed (-32000)​

When converting large documents, this error may appear in your logs. Increasing Gotenberg's memory allocation is a commonly suggested solution.

For additional details, refer to issue #788.

Dealing with Timeouts​

If you are experiencing timeouts (i.e., 503 Service Unavailable), consider the following steps to troubleshoot your issue:

  1. Assess whether your Gotenberg instance is overloaded. If this is the case, consider increasing the number of instances.
  2. Ensure that the page you are attempting to convert doesn't require resources inaccessible from the Gotenberg instance.
  3. Consider increasing the API timeout. See the API module configuration for guidance.
  4. Optionally, consider defining a maximum queue size to abort requests sooner. Refer to the Chromium module configuration for guidance.

LibreOffice​

PDF/A-1a​

Beginning with version 7.6, LibreOffice has discontinued support for PDF/A-1a.

Previously, LibreOffice claimed to generate PDF/A-1a files, a claim that held true for straightforward documents. However, in many instances, the software was actually producing PDF/A-1b files.

Due to specific metadata, some validators incorrectly identified these documents as compliant with PDF/A-1a standards, despite this not being the case.

For additional details, refer to this LibreOffice commit.

Internal Server Error​

If you consistently encounter a 500 Internal Server Error while attempting to convert an Office document, a common solution is to boost the memory and CPU resources allocated to Gotenberg.

For additional details, refer to issue #465.

Trouble Starting​

Startup failures can happen due to several factors. Here are some known solutions:

  • Increase the start timeout. See the LibreOffice module configuration for guidance.
  • For Debian users, it's recommended to use a current version of the distribution. For more information, refer to issue #794.
  • Users of Synology and Paperless-ngx should consult this comment for a proven configuration setup.

Dealing with Timeouts​

If you are experiencing timeouts (i.e., 503 Service Unavailable), consider the following steps to resolve your issue:

  1. Check if your Gotenberg instance is overloaded. If so, consider increasing the number of instances or enhancing the memory and CPU resources allocated to Gotenberg.
  2. Consider increasing the API timeout. Refer to the API module configuration for guidance.
  3. Consider increasing the LibreOffice instance startup timeout. Refer to the LibreOffice module configuration for guidance.
  4. Optionally, consider defining a maximum queue size to abort requests sooner. Refer to the LibreOffice module configuration for guidance.