Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Troubleshooting: frequently asked questions


Quick Index


1 Introduction

The XNAT Gateway server allows to query and retrieve DICOM images from XNAT servers using any DICOM client, such as DICOM viewer (OSIRIX, K-PACS, ...), MR scanner software, or PACS archive. You can install the Gateway locally and connect to it as to any other DICOM server. DICOM requests are translated into XNAT requests, and the result is returned over DICOM networking protocol.

2 Features

2.1 Querying for DICOM studies

You can browse the XNAT archive at Study (Experiment in XNAT) level and Series (Scan in XNAT) levels.

Use the following DICOM fields to query XNAT from your DICOM software:

DICOM search fieldXNAT field
Patient nameSubject label
Patient IDSubject ID
Accession numberExperiment label
ModalityImage session type

2.2. Loading DICOM images

Using Gateway, you can retrieve an entire study or an individual series. Image-level retrieve is not supported. 

NOTE. Currently, Gateway supports C-MOVE only (this is default in most DICOM software).

 3. Installing and running

Please refer to the installation page to download the correct package for your platform.

4. Application folders


src(application source code)
config(configuration files)
dist(distributed application JAR)
doc(location of this manual)
build(class files generated during compilation)
lib(external libraries needed by this application)
nbproject(configuration files for the Netbeans IDE)

5. The Main Screen

Once the server is configured this will be the first screen you see:

 Image RemovedImage Added

Status Screen

  1. Shows whether the server is running or not. "Running" indicates the server is listening for incoming requests from other DICOM devices such as Osirix. "Stopped" indicates that the server is not listening and incoming requests will fail.
  2. Shows how long the server has been running. This is reset everytime the server is (re)started.
  3. Stops and starts the server.
  4. Shows the server logs.
  5. Allows you to configure XNAT servers. Explained in Configuring XNAT Servers.
  6. Allows you to configure dicom devices including this XNAT Gateway and remote DICOM devices.

6. Initial Configuration

The first time the XNAT Gateway GUI is run, you will see the initial setup screen.

 Image RemovedImage Added

Initial Setup Screen

  1. Since the XNAT Gateway Server emulates a DICOM device it must have an AE (Application Entity) title. This is the DICOM name by which your image viewing software will refer to the server. Any unique name, such as "XNATGATEWAY" will do.
  2. The server also requires a port number on which to listen for incoming requests. Any port number that is not currently in use will do, typically for DICOM devices 4006 and 4008 will work.
  3. A unique name that refers to the default XNAT server. For example if the XNAT server is "", "CNDA" would work well.
  4. The actual hostname or IP address of the XNAT server. The CNDA, for example, is located at "".
  5. Your username for this XNAT server.
  6. Your password for this XNAT server.
  7. Keep these settings and start the server.
  8. Exit the application.

This form must be filled out completely in order to start the server.

7. Configuring XNAT Servers

You can now define multiple XNAT servers from which to query and retrieve images although only one is active at any given time. The following screen shows an overview of the current XNAT servers listed and the ability toggle a default server, and add and edit new servers:

Image RemovedImage Added

Configure XNAT Servers Screen


7.1 Adding an XNAT Server


Image RemovedImage Added

Adding an XNAT Server


7.2 Editing an XNAT Server

Image RemovedImage Added

Editing an XNAT Servers


8. Configuring DICOM Devices

The Local/Remote AE Configuration screen shows the current setting for this XNAT Gateway and the devices that are able to retrieve images.

Image RemovedImage Added

Local/Remote AE Configuration Screen


8.1 Configuring the XNAT Gateway

Change this XNAT Gateway's settings from this screen:

 Image RemovedImage Added

Gateway Settings Screen


8.2.1 Adding a Remote DICOM Device

The following screen allows you to add a new remote device:

Image RemovedImage Added

Add Remote AE Screen


8.2.2 Editing a Remote DICOM Device

The following screen allows you to edit an existing remote device:

Image RemovedImage Added

Edit Remote AE Screen

  1. The AE title of your DICOM image viewing software. Please refer to your DICOM software to get this information. This must be one word with no spaces.
  2. The hostname or IP address of the PC on which the DICOM image viewing software is installed.
  3. The DICOM port on which your DICOM image viewing software is listening for connections.


9. Advanced

9.1 The Properties File

All the configurable options of the XNAT Gateway Server are stored in "./<XNAT_SERVER_INSTALL_DIR>/config/" where XNAT_SERVER_INSTALL_DIR is the root directory containing the XNAT Gateway Server source code and documentation.

This properties file contains a number of settings some of which can be changed in the GUI. Please do not edit this file while the application is running.

This file is read on application startup and written as you make changes to the application settings (eg. if you add a new XNAT database). If there is an error in the properties file that setting is ignored, and a backup properties file is created. If a change you made is not appearing in the GUI this is the first place to look.

 9.1.1 Accessing the Properties Backup File

In case of error in reading the properties file, it is backed up to "" in the application root directory.

9.1.2 Adding An XNAT Server Manually


  1. After stopping the application open the properties file in a text editor.
  2. Determine a unique name for the device, eg. OSIRIX
  3. Add the device name to end of "Dicom.RemoteAEs". For the OSIRIX example, if the Dicom.RemoteAEs property is currently "Dicom.RemoteAEs=MYDEVICE MYOTHERDEVICE", append OSIRIX to the end of that line so it reads "Dicom.RemoteAEs=MYDEVICE MYOTHERDEVICE OSIRIX"
  4. Add this device's AE title to Dicom.RemoteAEs.<NAME>.CalledAETitle. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.CalledAETitle=DEVICE_AE_TITLE"
  5. Add this device's hostname to Dicom.RemoteAEs.<NAME>.HostNameOrIPAddress. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.HostNameOrIPAddress=your_hostname".
  6. Add this device's listening port to Dicom.RemoteAEs.<NAME>.Port. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.Port=listening_port".
  7. Save the file and restart the application.

9.1.4 Error Tracking

If you encounter retrieve error when the DICOM images from XNAT server are not displayed in the workstation:

  1. in the properties file, set
  2. restart the server,
  3. check the server log for DICOM exchange messages, and gateway.log file for XNAT-specific error messages.

9.2 XNAT Gateway Server Settings


SettingGUI ConfigurableDescription
Dicom.CalledAETitleYesThe AE title of this XNAT Gateway Server.
Dicom.ListeningPortYesThe port on which this XNAT Gateway Server listens for incoming requests from DICOM devices.
Logger.OutputNoConfigures where errors are sent. The default setting is "file" - if it is changed no logging will occur. The log file is hard-coded to "gateway.log" in the application's root directory..
Dicom.DebugLevelNoControl the verbosity of log messages. This defaults to 1 which just logs warning messages. Anything above 2 logs a huge amount of data (on the order of thousands of messages per transaction) so please use values above 2 only for debugging purposes.
Application.SavedImagesFolderNameNoThe location where images retrieved from the XNAT databases are stored. Every time the server is (re)started, these images are deleted. By default the location is set to the temporary directory of your operating system.
XNATServersYesA list of XNAT databases
XNATServers.defaultYesThe default XNAT database.
XNATServers.<NAME>.ServerURLYesThe hostname of the <NAME> XNAT database
XNATServers.<NAME>.UserYesThe username of the XNAT database
XNATServers.<NAME>.PassYesThe password of the XNAT database
Dicom.RemoteAEsYesThe list of DICOM devices that can retrieve images via this server
Dicom.RemoteAEs.<NAME>.CalledAETitleYesThe AE title of the <NAME> DICOM device
Dicom.RemoteAEs.<NAME>.HostNameOrIPAddressYesThe hostname of the <NAME> DICOM device
Dicom.RemoteAEs.<NAME>.PortYesThe port on which the <NAME> DICOM device listens for DICOM data.

10 Frequently asked questions & troubleshooting

Q1: When I try to start the XNAT Gateway in Linux, I get the message: "Server startup error! Permission denied (Bind failed)."
A1: This is most likely due to Linux security policy. Go to AE configuration->change/configure->Gateway Settings->change. Use server port number > 1024.

Q2: Any DICOM query to XNAT Gateway fails.
A2: Starting with October 2017 version, DICOM Query is by default restricted to specified DICOM Application Entities (AEs). Use AE configuration->Chage/Configure->Remote Devices to configure all DICOM clients that will be quering the Gateway.
To allow query from any AE, edit the config/qrscp-config.xml, and change the line
<attribute name="UnrestrictedQueryPermissionsToAETitles" type="java.lang.String">NONE</attribute>
to the line:
<attribute name="UnrestrictedQueryPermissionsToAETitles" type="java.lang.String">ANY</attribute>

Q3: DICOM query to XNAT Gateway works, but I can't download DICOM studies.
A3.1: Make sure that the condition in A2 is satisfied.
A3.2: Make sure that the DICOM data hosted by XNAT server has DICOM-conformant UID tags populated (StudyInstanceUID, SeriesInstanceUID, Patient ID).
A3.3: If C-GET doesn't work, try C-MOVE (configure your DICOM software to use C-MOVE to retrieve images)
A3.4: There may be an issue with your local XNAT server's CA SSL certificate. Gateway may not work properly with some types of SSL certificate at target XNAT server.  Test your Gateway+DICOM client setup against a public XNAT server such as

Q4: I need to change the way XNAT fields are mapped to DICOM fields by Gateway. Is there an easy way to do that?
A4: Refer to this discussion.