Modifying XNAT to Run on Tomcat 8.5 and Later

This page describes how to modify the XNAT war or deployed application to run under different versions of Tomcat.

As of version 1.8.2 (currently in development), XNAT is built to work with Tomcat 8.5 by default. If you are running Tomcat 7.0, support for it ended on 31 March, 2021 and it will be removed from many repositories before too long. You should consider migrating to Tomcat 8.5 as soon as possible. There are no known issues with running on Tomcat 9.0, but this is not yet an officially supported deployment scenario.

Running XNAT 1.8.1 and earlier with Tomcat 8.5 and later

The default war for XNAT 1.8.1 and earlier is built to run under Tomcat 7. If you need to use Tomcat 8.5 or 9, you should consider upgrading to XNAT 1.8.2, but if you can't:

  1. Extract the file META-INF/context.xml (this requires having the Java JDK available on your path):

    $ jar xf xnat-web-1.8.1.war META-INF/context.xml


    This file should look something like this (edited for clarity):

    <?xml version="1.0" encoding="utf-8"?>
    <Context>
        <Loader className="org.apache.catalina.loader.VirtualWebappLoader" searchVirtualFirst="true" virtualClasspath="${xnat.home}/plugins/*.jar"/>
        <JarScanner scanAllDirectories="true" />
        <Parameter name="xnatHome" value="${xnat.home}"/>
        <Manager pathname="" />
    </Context>
  2. Edit META-INF/context.xml and delete the line with the <Loader> element.
  3. Add the following lines to the file right after the <Context> element:

    <Resources>
        <PostResources className="org.apache.catalina.webresources.DirResourceSet" base="${xnat.home}/plugins" webAppMount="/WEB-INF/lib" />
    </Resources>
    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />
  4. Save the file and close your editor.
  5. Update the war file with your modified META-INF/context.xml file:

    $ jar uf xnat-web-1.8.1.war META-INF/context.xml
  6. Continue with your deployment/installation using the updated war file in place of the standard XNAT application.


The standard releases of XNAT 1.8.1 and earlier already have the lines required for Tomcat 8 compatibility, but they're commented out. Delete the <Loader> element then delete the "!--" string at the beginning of the <Resources> element and the "--" string at the end of the <CookieProcessor> element.

The final version of your modified configuration file should look like this:

<?xml version="1.0" encoding="utf-8"?>
<Context>
    <Resources>
        <PostResources className="org.apache.catalina.webresources.DirResourceSet" base="${xnat.home}/plugins" webAppMount="/WEB-INF/lib" />
    </Resources>
    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />
    <JarScanner scanAllDirectories="true" />
    <Parameter name="xnatHome" value="${xnat.home}"/>
    <Manager pathname="" />
</Context>

Running XNAT 1.8.2 and later on older versions of Tomcat

If you are preserving a legacy Tomcat environment and want to upgrade XNAT in that environment, see Modifying XNAT to Run on Tomcat 7

$label.name