PDF export in Confluence Data Center

Still need help?

The Atlassian Community is here for you.

Ask the community

When you export a space to PDF, Confluence exports the content of each page to HTML, converts that HTML to PDF, and then finally merges all the pages together into a single PDF file. This can be quite memory and CPU intensive, and has been known to cause out of memory errors when processing spaces with very long or complex pages. 

In Confluence Data Center we minimize the impact by handling the export in an external process pool, which is a seperate pool of processes, managed by Confluence. These processes (also known as sandboxes) can crash or be terminated, and will be restarted automatically by Confluence, without affecting the Confluence application itself.  

The external process pool is only available for Confluence Data Center.

In Confluence Server, PDF export is handled by Confluence, so the information on this page does not apply. 

Troubleshooting failed exports

Exporting an entire space to PDF can sometimes fail, especially if the space is very large, or has very long or complex pages. If PDF export fails you'll see one of the following errors in your browser. 

Page took too long to convert

This error occurs when the time it takes to convert the HTML of a page to PDF exceeds the set time limit. The page title will be included in the error message. 

You should take a look at the page, and see if it can be simplified. It might have a lot of complex macros, or a lot of web images (images that are not attached to the page).  If this error happens a lot, you can ask your admin to increase the time limit.

Error converting page to HTML

This error occurs when Confluence runs out of memory, or hits another error while trying to convert the HTML of a page to PDF.  The page title will be included in the error message. 

As with the 'page took too long to convert' error above, you should take a look at the page, and see if it can be simplified.

Confluence admins can get more information about the cause of these errors from the Confluence application logs. If the failures are being caused by out of memory errors, your admin may be able to increase the amount of memory available to each sandbox in the external process pool. See External Process Pool for Confluence Data Center for more information. 

Final PDF file wasn't merged in time

This error occurs at the last stage of the process, when the time it took to stitch together all the individual page PDFs into one PDF file, exceeds the set time limit. 

If you hit this error you could try exporting the space again, or perhaps export the space in two sections (using the custom option on the PDF export screen). If this error happens a lot, you can ask your admin to increase the time limit.

Error merging the final PDF file

This error occurs when Confluence runs out of memory, or hits another error, when attempting to stitch together all the individual page PDFs into one file. 

If you hit this error you could try exporting the space again, or perhaps export the space in two sections (using the custom option on the PDF export screen).

Confluence admins can get more information about the cause of these errors from the Confluence application logs. If the failures are being caused by out of memory errors, they may be able to increase the amount of memory available to each sandbox in the external process pool. See External Process Pool for Confluence Data Center for more information. 

Too many concurrent exports

This error occurs when multiple people are exporting to PDF at the same time. Confluence limits the number of PDF exports that can be processed concurrently. 

If you hit this error, try exporting the space again later, after the other PDF exports have completed.  

If this error happens a lot, your admin can increase the maximum number of concurrent PDF exports, or increase the time Confluence should wait when the maximum number of concurrent PDF exports has been reached using the following system properties:

confluence.pdfexport.permits.size
Use this property to set the maximum number of concurrent PDF exports that can be performed. This property applies per node, not per sandbox process.  

confluence.pdfexport.timeout.seconds
Use this property to set the amount of time a new PDF export request should wait before failing, if the maximum number of concurrent PDF exports has already been reached. 


Change the time limit

Processes are automatically terminated once a time limit is exceeded. You can increase the time limit for PDF export using the following system property:

pdf.export.sandbox.request.time.limit.secs
Use this property to set the amount of time (in seconds) that a process should wait to complete, before being terminated. This time limit applies both to the time to convert the content from HTML to PDF, and the time to merge the final PDF file.

See Recognized System Properties for a full list of properties, including a few additional properties that can be used to fine-tune, or disable the sandboxes for a particular action. 

Don't use the external process pool for PDF export

If you don't want to use the external process pool for PDF export, you can revert back to the Confluence Server method of generating PDF exports using the following system property:

pdf.export.sandbox.disable
Set this property to true if you don't want to handle PDF exports in the external process pool.

Last modified on Aug 22, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.