Compass Troubleshooting Tips

Compass isn’t applying an expected filter

• Verify that the association matched with the correct Source. A typical issue is having a Source that is too generic earlier in the list of Sources.
• Check the conditions of the filter. Turn Logging on for the given Source or Destination.

Check the “Inbound Association History”

• Confirm the presence of an entry for the selected modality
• If there is no entry for the selected modality, the connection request is not getting to Compass
• A networking or configuration issue is the most likely cause, often resolved if the following is done:
  • Check the firewall settings
  • Check the IP address and port to which the modality is sending
  • Confirm these settings in Compass
  • Verify on the Compass main screen that “DICOM Input” is running

Look for a non-Accepted entry

• An entry in the “Inbound Association History” shows a result other than “Accepted”
• Match the entry in the Result column with one of the following results:
  • “Bad Calling Title”: the modality’s AE title is invalid
    • Check the Source AE title on the Source tab
    • Verify that the “Source Enabled” checkbox is checked
  • “Bad Called Title”: one of the Compass AE titles is invalid
    • Check the Compass AE title on the Source tab
    • Verify that the “Source Enabled” checkbox is checked
  • “No Requested Contexts Accepted”: no context ID (combination of image type and transfer syntax) was accepted
    • Check the Compass list of supported SOP classes on the System tab
    • Check the list of enabled transfer syntaxes on the Source tab
  • “Max Concurrent Associations for Source Exceeded”: too many concurrent connections were attempted
    • Check the “Max Simultaneous” checkbox on the Source tab

Check filters on the Source

• Check filters specified on the Source
• Verify that there is not a filter that tries to modify a tag that is missing in the C-Echo from the Source
  • For example, if a filter that attempt to modify the Accession Number tag, but a preliminary C-Echo from the Source does not contain an Accession Number, the connection will be rejected
  • Verify that filters that attempt to modify a tag check first for the existence of that tag

Compass is rejecting an association

• When an association is requested, Compass evaluates the list of Sources starting at the top of the list and works its way down until it finds a match.
• Check the IP address and AE titles of the requestor to determine if they don’t match any of the Sources.
  • A common issue is inadvertently reversing the calling (Source) and called (Compass) AE titles.
  • Viewing the Inbound Association History under the View menu can be helpful.
• Compare the presentation context list that the SCU is requesting with the list of transfer syntaxes that the matching Source has enabled and also the list of supported SOP classes.
  • Enabling Logging can help to verify this.
  • Be sure to disable logging once issue is solved.

Compass is filling up the hard drive with images

• Configure the “Low Disk Space” notification, if possible
• Confirm that the amount of available hard drive space is adequate for the configured purge settings and workflow
• Check to see if the “Sent Job Purge Delay” is too large given current workflow load and hard drive capacity, and if too high lower this number.
• Check for excessive numbers of Failed jobs and correct issues causing the Failed jobs.
• Check for excessive jobs in the Hold Queue and correct issues with Hold Queue jobs.
• Check for excessive Queued jobs and correct issues with Queued jobs.

User cannot remember password for the web interface

• For versions 2.4.x and later, in order to reset the Administrator password to the default (found in the Compass user manual), do the following:
  • Stop the web UI by unchecking the ‘Enabled’ checkbox for the Web Interface on the DICOM Options dialog.
  • Click Ok.
  • On the System tab, click the ‘edit’ link in the Compass Web User Administration section.
  • Click the Administrator Password Reset button (enabled if LDAP is disabled), which resets the password to the default value (found in the Compass user manual).
  • After successfully logging in with the default password, the password should be immediately changed to a non-default, secure value (12+ characters, including uppercase and lowercase characters plus numeric digits).
  • Start the web UI by re-checking the ‘Enabled’ checkbox for the Web Interface on the Options dialog.
  • Click Ok.
• For versions prior to 2.4.x, in order to reset the password to the default (found in the Compass user manual), do the following:
  • Stop the web UI by unchecking the ‘Enabled’ checkbox for the Web Interface on the DICOM Options dialog.
  • Click Ok.
  • Delete the following file:
    “C:\ProgramData\Laurel Bridge Software\Compass2\www\App_Data\CompassData.sdf”
  • Note that the above file location is for Windows 7 and may be different if on another OS. The name of the file will be the same, however.
  • Start the web UI by re-checking the ‘Enabled’ checkbox for the Web Interface on the Options dialog.
  • Click Ok.

License fails to install

• Verify that the C:\ProgramData\Laurel Bridge Software\Compass2 is not set to be read-only.
• Note that Compass cannot install a license that is on a network drive. Copy the license file to the local drive to complete installation.
• Determine whether the license is a MAC based license or an activation license.
  • A MAC based license is installed by pressing the ‘Install License…’ button.
  • An activation license is installed by pressing the ‘Activate License…’ button.

Troubleshooting questions to ask when Compass appears to be running slowly

• Is logging turned on any Compass Source/Destination or is the global log level on the Compass System tab set to a level higher than ‘Terse’ ? If it is turned on anywhere, trying turning it off or to Terse and see if that fixes the problem.
• How much memory is available to Compass?
• How much free disk space is there?
• Approximately how many studies are sent to Compass per day?
• Do you have any Compass Destinations configured as ‘Immediate Mode?’ That feature can be accessed at the top of the right-hand column of the Destination configuration tab.
• What is the total number of jobs sitting in Compass including Failed and Sent jobs?
• What is the Sent jobs purge delay set to on the Compass System tab?
• Is Compass running on a virtual machine (VM)? If so, are there multiple snapshots?
• Review settings for concurrent associations:
  • How many concurrent inbound associations are there? (This is configurable on a per-Source as well as System-wide setting).
  • How many concurrent outbound associations are there? (This is configurable on a per-Destination as well as System-wide setting).
  • One or both of these values may be too high.
• Is Compass changing the transfer syntax?
  • Many concurrent associations, usually with large images, that are changing transfer syntaxes can bog Compass down.
  • Configure Compass to either not change the transfer syntax (if possible), or lower the concurrent association count(s) (see “Review settings for concurrent associations” above).
• What is the refresh rate set to on the main Jobs table? Set this value to a less frequent value.

Compass cannot be successfully uninstalled

When attempting to uninstall Compass, and the uninstallation process fails, try the following:

• Navigate to the Compass installation directory:
  C:\Program Files\Laurel Bridge Software\Compass2
• Drag the following install state file to the desktop:
  CompassService.InstallState
• Retry uninstallation, which may now work

Compass

• Failure stops traffic – this is on by default. Try disabling.
• Retention time for HL7 messages – if retention time is too long, the limit (e.g., 100K messages) may be reached and HL7 processing will stop. Try adjusting retention time for HL7 messages.
• Disk filling up – if Compass is running on a system with a modest size disk drive, and images and/or logging is enabled, the drive may be filling up. Suggest turning off images or logging, if applicable, or using a larger disk drive.
• Sources and destinations – although HL7 input or output may be enabled (“running”), if HL7 traffic is not processing look for sources or destinations that are not “started”. Look for pertinent status in one of the HL7 display screens.
• Loopbacks – verify that source and destination HL7 ports for Compass (and Navigator) are not configured to create a loopback condition in Compass.

Navigator

• Automatic start – verify that “automatically start worklist item processing” is enabled, if appropriate. This is near the top of the screen in Configuration -> General Settings.
• Study Rules – if a study rule was added, make sure that that rule is referenced by the appropriate worklist-reader, and that the list of rules for the worklist reader is in the proper order. Note that every Navigator study rule is “stop on match” in Compass terminology.
• Running status – view status indicators in the dashboard area. Navigator notes when the HL7 service is running and indicates status via red or green HL7 display.

General

• Command prompt diagnosis – to determine whether or not DICOM or HL7 listeners are working correctly, from a command prompt run:  netstat -ano
  Explanation: “a” means all, including unconnected listening ports, “n” means don’t delay things by trying to get dns name for every ip addr, “o” means show the process id for the app on this side of the connection. You can check the process-id against task manager to make sure its who you think it should be.

Most likely cause is a rule configuration error

• Verify that the rule is enabled
• Verify that the conditions for the rule are correct
  • For example, the condition should say “Accession # equals 123” and not “Accession # equals 124”
• Enable logging for the Source
  • Logging captures the header data for each image along with the rules the image matched
  • Be sure to disable logging after the problem has been resolved.
  • It is recommended to use this logging information only for specific troubleshooting, as logging can generate a large amount of data and negatively impact Compass and system (especially on a virtual machine) performance.

A study doesn’t appear in Compass

• Check the “View” filter for the Jobs table
• Check purge settings on System tab in case the Study was auto-purged

Compass isn’t receiving images

• Verify that the system is powered on
• Verify that Compass is installed
• Verify that the Compass service is running
• Determine if images are being sent to the correct server and port number
  • Checking “Inbound Association History” under the View menu is helpful for determining if an association request is getting to Compass.
  • Determine whether Compass is truly rejecting the association or the image is simply never getting to Compass. Note that some SCUs may inaccurately report association rejection when the underlying issue is an underlying configuration problem, such as an incorrect server or port number.
• Determine if there is a connection protocol mismatch, such as attempting to connect to the SSL/TLS port with an unencrypted association request and vice versa.
• Verify that Compass has Input enabled.
• Verify that a firewall is not blocking traffic to or from Compass.
  • Note that Windows Updates being applied or a normal system restart can re-enable the firewall, so it may be necessary to reopen the appropriate ports to allow traffic through the firewall.

Compass isn’t ingesting hotfolder files

• Verify that the correct path is selected for the hotfolder.
• Verify that a correct File Mask is in use for the hotfolder.
• Determine if the Stability Time of the hotfolder is too long.
  • Compass will not ingest any files until all files in the folder have satisfied the Stability Time.
• Compare the transfer syntax of the image in question with the list of enabled transfer syntaxes in the hotfolder definition.

Compass accepts the images but they don’t show up in the jobs table

• Determine if the “view” setting has filtered out images from view.
  • For example, a typical issue is:
    • A study for patient name “Bob” was sent,
    • But the view is restricted to the patient name “Steve”.
    • In this case, the image will not be seen until the view is not restricted to “Steve”.

Compass doesn’t appear to be accepting the SOP class that is being sent

This is an example that illustrates a scenario where you might need to add a SOP class UID to the Compass list of supported SOP classes.

• I am trying to send Cardiac US to Compass. I see that Ultrasound Multiframe Image Storage SOP class is acceptable by Compass, however it is not accepting images sent from the US cart.
• Compass by default supports Ultrasound Multiframe Image Storage, with a SOP class UID of 1.2.840.10008.5.1.4.1.1.3.1.
• There is another similar SOP class that is retired: Ultrasound Multiframe Image Storage (Retired), with a SOP class UID of 1.2.840.10008.5.1.4.1.1.3.
• This UID is not in Compass’ default list of supported sop class UIDs. If this is what your device is sending, it’s easy to add it.
• First, you’ll need to stop Input and Output on Compass.
• Then go to the System tab on the Options dialog.
• Click the “Edit Supported SOP Classes” link and add the UID and its name to the list.
• Restart the Compass Input and Output and the retired SOP class should now be accepted.

Compass accepts images but then just deletes them

• Determine if routing rules have been inadvertently configured with a rule containing a “Discard Instance” action.
  • Rules are evaluated in order, starting at the top and continuing until a match is found.
  • The exception to this ordering is when “Stop Rule Processing on Match is unchecked, in which case rule processing will continue after a match.
• Determine if there are no matching rules present and also the “Report errors for non-routed images” checkbox is unchecked on the Sources tab.
  • This scenario is equivalent to the “Discard Instance” action on the rules tab.
  • To troubleshoot, set the Log Verbosity to “VerboseDicom” on the System tab to log information about what rules are being matched.

Compass is routing images to the wrong destination(s) or doesn’t route them at all

• Determine if the images are matching the expected Rule.
• Determine if there is a Rule that is too generic which may be matching prior to the expected one.
• Determine whether or not an image in question is satisfying the defined conditions in the Rule.
• Determine if the Rule that is expected to match has its “Rule Enabled” checkbox checked.
• Review the list of “Selected Destinations” for the Rule looking for potential problems.
• Turn logging on for the Source. This will log which rule each image matched.

Jobs in Compass are stuck in the Queued state

• Verify that Output is enabled
• Verify that the Destination has its “Enabled” checkbox checked. This can be checked via the “Source/Destination Status” dialog under the View menu.
• Determine if the Destination’s schedule is active. This can be checked via the “Source/Destination Status” dialog under the View menu.
• Check the Destination’s “Initial Delay” setting for an excessive value.
• Check the Destination’s “Retry Delay” setting for an excessive value.
• Determine if the Destination’s “Heartbeat Sensing Enabled” checkbox is checked. If so, check if the last heartbeat was successful. This can be checked via the “Source/Destination Status” dialog under the View menu.
• Determine if the “refresh rate” of the Jobs table is set to Manual. If so, the current view may be a stale copy of the view.
• Determine if the maximum concurrent association count has been reached for the Destination and/or for Compass as a whole. Enable the “Active Associations” table under the View menu to see a list of all open associations.

One or more Images have been successfully sent to Compass, but these Images are not being sent to the correct destination(s)

• Most likely of this issues is a rule configuration error:
  • Verify that the rule is enabled and that conditions are correctly specified
  • Verify that there is not rules that are no incorrectly matched rules, looking for images that match a rule in a way that was unintended
  • Verify that the “Discard Instance” action was not unintentionally selected
  • Verify that “Report errors for non-routed images” is checked
  • Enable logging for the Source
    • Logging captures the header data for each image along with the rule matching information
    • Be sure to disable logging after the problem has been resolved.
    • It is recommended to use this logging information only for specific troubleshooting, as logging can generate a large amount of data and negatively impact Compass and system (especially on a virtual machine) performance.

Studies won’t sent at all

• Verify that “DICOM Output” has a status of “Running” on the Compass main screen
• Verify that “Destination Enabled” on the Destination tab is checked
• Verify that the schedule for the destination on the Destination tab is correct
  • For example, a schedule is configured to send only at night but it is currently daytime
• Verify the heartbeat status of the destination by viewing the DICOM Source/Destination Status under the View menu)

Studies fail to send

• Check the Message column in the Jobs table
• Check the Job Report
  • Right-click on the failed job and select “View Job Report”
  • Note that problems with sending studies from Compass may have a similar cause as problems with sending studies to Compass
• Enable logging for the Destination
  • Logging captures the header data for each image along with the response code from the destination
  • Be sure to disable logging after the problem has been resolved.
  • It is recommended to use this logging information only for specific troubleshooting, as logging can generate a large amount of data and negatively impact Compass and system (especially on a virtual machine) performance.
• Verify that any filters specified on the Destination are modifying data as expected
• The Destination may also reject images for more complicated reasons, such as:
  • Duplicate images reside on the PACS
  • Invalid header data is present (for example, the accession number is not in the format expected by the PACS)
  • Parsing the pixel data is problematic (for example, converting a JPEG image to a thumbnail)