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.
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 TOMCAT_HOME/webapps/PROJECT/logs. Within the webapp, you will find the folllowing 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. Most prominently, this file contains messages from the pipeline engine.
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.
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.
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).
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 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 standardly 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]
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 application.log. If the exception isn't there, then it will often be logged in pipeline's own log structure.
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.
XNAT's support for SMTP is currently fairly limited. XNAT currently expects you to have access to an unauthenticated SMTP server. Normally, XNAT is installed within a firewall and this requirement is tolerable by systems administrators. However, in some scenarios, support for SMTP authentication is required. The XNAT team is working on refactoring the XNAT email code to be more robust to these needs.
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:
- 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.