Configuring Tomcat

Most issues with XNAT that have root causes in Tomcat configuration relate to various issues in memory usage and configuration. If you're seeing issues that are not covered on this wiki page, you can submit a question to the XNAT discussion group or check out the following resources:

Heap Errors

If your heap memory is configured too low (or not configured at all, which uses the JVM default heap size), you may see an error like this:

Horrible Exception: java.lang.OutOfMemoryError: Java heap space

The “horrible exception” verbiage is Tomcat-specific, but the rest of the error is a standard message from the JVM when the heap space blows out. This is easily handled, but the method for fixing it depends on the platform on which you’re running Tomcat:

  • On Linux, add a file named into the bin folder of your Tomcat installation. Tomcat runs this script on server start up when present. This gives you an opportunity to set values in the environment. When you create this script (or modify an existing instance), pay attention to script ownership and file permissions: you’ll want these settings to be the same as the other scripts in your Tomcat bin folder. Add something like this to your script:

  • Another option on some Linux and Tomcat platforms is to modify the tomcat.conf configuration file to include these options on service start-up. There is usually already a line configuring the JAVA_OPTS setting, although it may be commented out. You can uncomment and/or set the appropriate values on this line of the configuration file.
  • If you’re running Tomcat as a service on Windows, start the service configuration utility as administrator. This utility can be found in the Apache Tomcat x.y program menu as Configure Tomcat. Right-click on the icon and select Run as Administrator. Without this, Windows usually won’t let you change the configuration. When the configuration utility appears, select the Java tab and add the following two lines in the Java Options text box:

  • If you're running Tomcat with a batch file (e.g. startup.bat) on Windows, you can set your heap settings a couple different ways. You can create setenv.bat in the Tomcat bin folder, similar to the mentioned earlier for Linux (in that case, you need to add set to when setting CATALINA_OPTS, as well as use Windows environment variable expansion, so the command becomes set CATALINA_OPTS=%CATALINA_OPTS% -Xms512m -Xmx1024m). You can also set the CATALINA_OPTS environment variable at the system level, in which case it will be picked up when you restart Tomcat (if you're launching from a command prompt, you'll need to restart the command prompt as well).

Once you've made one of these configuration changes, you'll need to restart Tomcat for the changes to go into effect.

About these options:

  • The -Xms option sets the starting heap space available to the JVM. Setting too large a minimum value can slow Tomcat start-up time, as well as take physical and virtual memory space from other processes on your server, with no guarantee that your process will ever use it. That said, this can be a valuable performance enhancement when XNAT is initializing. Try different values for this to help speed XNAT start-up without degrading the performance of other services and applications on your server.
  • The -Xmx option sets the maximum heap space available to the JVM. If you're getting a Java heap space error, this is really the figure that you’re interested in. Increasing this number increases the maximum amount of memory that Tomcat can consume while running. The default value for this depends on the version of the JVM you're using, the platform on which you're running, and the physical memory available on the hardware. However, the default value is often too small for computationally intensive applications like XNAT, so try increasing the value of this setting until your server can run under production loads.

In addition to these settings, some users of XNAT have reported seeing heap errors related to deploying XNAT into Tomcat as a WAR. If you modify the -Xmx settings and continue to see heap errors, you may try deploying XNAT using the -Ddeploy=true option on the setup or update script command line, e.g.:

bin/ -Ddeploy=true
bin/ -Ddeploy=true

PermGen Errors

A problem that is similar and sometimes related to heap errors is running out of perm gen space:

Horrible Exception: java.lang.OutOfMemoryError: PermGen space

This is related to the JVM object allocation and garbage collection mechanism. A technical discussion of the perm gen space and tuning JVM garbage collection can be found on the Oracle Java site. Generally, though, you won't need to know all of the in-depth technical information and will just need to set an option to increase the perm gen space. You can use any of the techniques described in the previous section to set the option. The actual text for the option is:


Even more than the -Xmx option, it's very important that you experiment with different values for this option. Too small a perm gen size can obviously lead to the out-of-memory error above. Too large a perm gen size can lead to significant degradation in Tomcat performance over time as objects accumulate in the perm gen pool. However, the perm gen pool relates directly to the heap, so increasing your heap size can lead to perm gen errors, necessitating changes in your perm gen configuration.

For other good tips and options for configuring your perm gen space, as well as a little background in what's going on with these settings, check out this post by Mark Kolich.