Troubleshooting Tips

What's wrong with my XNAT? When you encounter problems with your XNAT server, there are specific resources you can use to try to identify the cause(s) of your problem.

Available Logs

XNAT is configured to log important errors and events to a collection of log files. The majority of these log files are contained in the XNAT_HOME/logs. Within the webapp, you will find the following logs:


This log contains all of the site access by the users of the site. This is a useful place to see who is or has been logged into your site or to track down usage statistics.


This log contains messages from tools which have been added to the XNAT platform.

automation.logThis log contains errors coming from XNAT's Automation service.


This log is used by the avalon framework. For the most part, it can be ignored.


This log is used by the deprecated SOAP web services. If you don't specifically use these services, this file can be ignored.

launch.logThis log contains the launch strings for all pipelines run through XNAT. Read more here: Monitoring and Troubleshooting Pipelines.
pipeline.logThis log contains the launch strings for pipelines that failed to execute. Read more here: Monitoring and Troubleshooting Pipelines.


This log is used by Turbine's scheduling tool. It can be ignored.


This file contains errors regarding connections to the database. Anytime an SQL query fails to run, it will be logged here.


This file contains messages from the Turbine framework. Unless you are adding a new action or report, it can probably be ignored.


This file contains messages from the velocity engine. Unless you are building a new VM screen, it can be ignored.

xapi.logThis log contains messages involving /xapi/ REST calls. Usually, the main content of this log is made up of changes to your XNAT instance through the Admin UI (and hence siteConfig API).


This file contains errors from XNAT (which is an extension of XDAT). This is the most likely place where meaningful error messages for your problems will show up.


This file contains messages from the XNAT FS server. If you aren't using XNATFS, then it can be ignored.

The only other log file which may be of interest is the TOMCAT_HOME/logs/catalina.out file. This file is created by TOMCAT and is a copy of the System Out of your server. If an exception is severe it may be caught here.

Report a Bug

The report a bug feature allows users to quickly generate an email to the site administrator detailing a problem. In addition, the auto-generated email contains much of the version information (XNAT, OS, Java, PostgreSQL, etc) which the XNAT team would likely request if they were trying to address your issue. The Report a Bug email includes directions for how site administrators should forward the issue to the XNAT team (though it could also be posted to the discussion group).

Discussion Group

The XNAT Discussion Group is an excellent resource when you are encountering unexpected behavior. The discussion group is hosted on Google Groups and is maintained by the XNAT team. The discussion group has been active for several years and is an excellent resource for getting to know XNAT and resolving any issues. A first step for using the discussion group would be to use the integrated Google Search within the group to try to identify issues similar to your own. Often other users have seen the same issue which you are seeing and a resolution may already be available. If after querying the site, you are still unable to identify the problem, you can post your own message to the discussion group and the XNAT team will be in touch.

Dealing with Common Problems

Memory Issues

Memory Issues often become apparent when the website noticeably slows down. In critical periods, the site can stop serving content at all for several minutes. This can usually be easily prevented by increasing the available memory. On a default XNAT installation, memory isn't usually an issue. However, once you start using the XNAT server more robustly with multiple users and scripts, memory can become an issue.

We typically run XNAT with at least 512MB of memory. On our production servers, we give the Tomcat process over 1GB of RAM. The Memory can be adjusted by modifying Tomcat's configuration. This is described in more detail on the Configuring Tomcat page. [Related: Tomcat documentation]

Site URL

XNAT functions best when users access the site at one URL. This URL should exactly match the SITE URL specified in the Administration -> Default Settings. This URL will be given to users when emails are sent to them by the XNAT server.

If the SITE URL is not set properly pipelines will often fail, the Download Images Applet will fail, and the Upload Images Applet will fail.


Pipeline failures are a common complaint from the XNAT community (and us as well). If your prearchive-archive transfers remain QUEUED for ever, then your pipeline engine is probably not setup properly.

If you encounter problems with pipelines, the first place to look is the pipeline.log. This logs all failed pipeline runs. If the exception isn't there, then it will often be logged in pipeline's own log structure. You may also try looking in launch.log.


XNAT attempts to send emails to users on several occasions. The most common is after a session is successfully transfered from the prearchive to the archive space. If the email fails to send (usually due to the absence of an SMTP server) then the archive process will show up as incomplete at 100%. If this occurs, review your SMTP configuration. See: Configure the Email Server (Notifications & Alerts)

XNAT currently expects you to have access to a valid SMTP server. In previous versions of XNAT, the support for SMTP servers was limited to only unauthenticated SMTP, but that impediment has now been removed. 

Help With Debugging

If you are encountering an issue in XNAT, here is a common workflow:

  1. Identify if the problem is repeatable. Can you describe a set of steps for other users to get the same issue?
  2. Review the system logs:
    1. xdat.log
    2. application.log
    3. catalina.out
  3. Review the XNAT Discussion Group. Did anyone else report a similar issue? Use the search interface to identify similar threads.
  4. Contact the XNAT team
    1. Use the Report a Bug feature to collect all of the necessary version information.
    2. Forward that information to the discussion group with a detailed explanation of how to duplicate your issue.