This documentation is for XNAT versions 1.6.0 - 1.6.5. You can find the latest documentation for XNAT 1.7 at https://xnat.org/documentation
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:
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:
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 setenv.sh 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:
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:
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:
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.:
A problem that is similar and sometimes related to heap errors is running out of perm gen 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.