Document conversion sandbox for Confluence Data Center

Still need help?

The Atlassian Community is here for you.

Ask the community

When you insert a file into a page (for example a Word document, or Excel spreadsheet), Confluence will generate thumbnail images of the file contents, so it can be viewed inline in the page, or in the preview. This can be quite memory and CPU intensive, and has been known to cause out of memory errors when processing very complex files. 

In Confluence Data Center we minimize the impact by handling the conversion in sandboxes, a seperate pool of processes, managed by Confluence. These processes can crash or be terminated, and will be restarted automatically by Confluence, without affecting the Confluence application itself.  

If you insert a very complex file, and the process crashes or is terminated, thumbnail generation will fail. When this happens, a placeholder thumbnail will be used on the page, and a download option will be provided in the file preview. Confluence Data Center doesn't re-attempt to generate thumbnails for failed files.  A good example of a complex file, is a PowerPoint presentation that contains 50 embedded Excel charts. Most files will be processed without any problems. 

The document conversion sandbox is only available for Confluence Data Center.

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

Memory requirements

You will need to make sure that every Confluence node in the cluster has enough memory for the sandboxes. We create two sandboxes by default, so we recommend allowing an additional 2 GB on top of what is already required for Confluence (1 GB per sandbox). 

You can increase the number of sandboxes available on each node using a system property. If you increase the number, make sure each node has enough free memory. 

Configure the sandbox

In most case the default values will be adequate, however system administrators can change the behaviour of the document conversion sandboxes using system properties. For example you may want to increase the size of the pool (the number of sandboxes), or increase the time limit before a process is terminated and thumbnail generation fails.  Here are the three main properties you may need to change:

  • document.conversion.sandbox.pool.size
    Use this property to increase the number of sandboxes (number of processes available). You'll need to allow additional memory on each node for each additional sandbox. 
  • document.conversion.sandbox.request.time.limit.secs
    Use this property to change the amount of time (in seconds) that the sandbox will wait for the document conversion process to complete, before terminating the process, and marking thumbnail generation for that file as failed. 
  • document.conversion.sandbox.memory.limit.megabytes
    Use this property to limit the amount of memory each sandbox process can consume. 

See Recognized System Properties for a full description of these properties, plus a few additional properties that can be used to fine-tune, or disable the sandboxes completley. 

Re-attempt thumbnail generation for failed files

Confluence does not re-attempt to generate thumbnails for a failed attachment, and re-inserting the attached file into the editor will not trigger the process. 

If you do want to re-attempt thumbnail generation, for example after increasing the request time limit, you will need to re-upload the file, and then re-insert it into the page. 

Monitor failed files

When a sandbox process is terminated, we'll write the following to the application log on that node:

2018-04-09 17:35:35 WARN [sandbox-terminator] 
[impl.util.sandbox.DefaultSandbox] lambda$startTerminator$0 Request 
has taken 33384ms exceeds limit 30000ms terminating sandbox

This will be followed by an Attempting to restart the sandbox message, the next time someone inserts a file, triggering a conversion request. 

Note that the sandbox is not immediatley restarted after termination, as we don't re-attempt thumbnail generation for failed files. We wait for the next conversion request to spin up a new sandbox instance. 

Last modified on Aug 13, 2018

Was this helpful?

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