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:
access.log | 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. |
|---|---|
application.log | This log contains messages from tools which have been added to the XNAT platform. |
| automation.log | This log contains errors coming from XNAT's Automation service. |
avalon.log | This log is used by the avalon framework. For the most part, it can be ignored. |
axis.log | This log is used by the deprecated SOAP web services. If you don't specifically use these services, this file can be ignored. |
| configuration.log | This log is used by XNAT configuration classes, mostly during initialization but also for changes to the XNAT configuration. |
| dicom.log | This log contains information relevant to processing DICOM data. |
| events.log | This log is used by the event service. |
| identifiers.log | This log is used by DICOM object identifiers and support classes when identifying projects, subjects, session labels, and configured metadata during DICOM extraction. |
| jdbc.log | This log is used by the Java database connection framework that XNAT uses to manage database transactions and data persistence. |
| orm.log | This log is used by the XNAT object-relational mapping framework. |
| prearchive.log | This log contains messages from the prearchive service, which receives and manages incoming DICOM sessions. |
| restlet.log | This log is used by REST API implementations in XNAT that use the legacy Restlet framework. |
scheduler.log | This log is used by Turbine's scheduling tool. It can be ignored. |
| security.log | This log is used by XNAT's security and authentication framework. |
| spring.log | This logs contains messages from XNAT's integration with the Spring Framework. |
sql.log | This file contains errors regarding connections to the database. Anytime an SQL query fails to run, it will be logged here. |
| tasks.log | This log contains messages from tasks running in XNAT's task management framework. |
turbine.log | This file contains messages from the Turbine framework. Unless you are adding a new action or report, it can probably be ignored. |
velocity.log | This file contains messages from the velocity engine. Unless you are building a new VM screen, it can be ignored. |
| xapi.log | This 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). |
xdat.log | 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. |
xnatfs.log | 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.date.log files. 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
You can follow and participate in the XNAT discussion group by going to the top page of the group and joining.
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 To Avoid Errors 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, as will upload or download operations from external tools.
Pipelines
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.
SMTP
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:
- Identify if the problem is repeatable. Can you describe a set of steps for other users to get the same issue?
- Review the system logs:
- xdat.log
- application.log
- catalina.out
- Review the XNAT Discussion Group. Did anyone else report a similar issue? Use the search interface to identify similar threads.
- Contact the XNAT team
- Use the Report a Bug feature to collect all of the necessary version information.
- Forward that information to the discussion group with a detailed explanation of how to duplicate your issue.