Deploying Orthanc: Step-by-Step Guide for Medical Imaging Teams

Troubleshooting Orthanc: Common Issues and Fixes

1. Orthanc won’t start

• Likely causes: port conflict, incorrect configuration file, insufficient permissions, missing dependencies.
• Fixes:
  1. Check logs (typically /var/log/orthanc/orthanc.log or systemd journal): journalctl -u orthanc or tail -n 200 /var/log/orthanc/orthanc.log.
  2. Verify configuration syntax: run a JSON/YAML validator on Orthanc config file.
  3. Confirm port availability: ss -tlnp | grep 8042 (adjust port if changed). Stop conflicting service or change Orthanc port.
  4. Ensure proper permissions on storage directory: chown -R orthanc:orthanc /var/lib/orthanc (or appropriate user).
  5. Install required dependencies and restart: systemctl restart orthanc and recheck logs.

2. Web UI inaccessible

• Likely causes: firewall, service not running, wrong host/port, reverse-proxy misconfiguration.
• Fixes:
  1. Confirm Orthanc process is running: systemctl status orthanc.
  2. Test local connectivity: curl -v http://localhost:8042/.
  3. Check firewall rules: ufw status or iptables -L and allow the port.
  4. If behind a reverse proxy (NGINX/Apache), ensure proxy_pass and headers (Host, X-Forwarded-For) are correct and proxy buffers/timeouts are sufficient.
  5. Review browser console/network for CORS or SSL certificate errors; adjust config accordingly.

3. DICOM peers cannot connect / association failures

• Likely causes: AE title mismatch, port blocked, TLS mismatch, network routing issues.
• Fixes:
  1. Confirm AE titles and ports match between Orthanc and the peer (Orthanc config: DicomModalities / DicomScp settings).
  2. Test adjacency with storescu/storescp (DCMTK) or using findscu/getscu to simulate associations.
  3. Check network connectivity and firewall between hosts (ping, traceroute, telnet).
  4. For TLS: ensure certificates, keys, and cipher suites match, and Orthanc is configured for TLS if peer expects it.
  5. Inspect Orthanc logs for DIMSE errors and increase log verbosity if needed.

4. Failed or incomplete DICOM transfers (corrupted/partial files)

• Likely causes: network interruptions, client timeouts, incompatible transfer syntaxes, storage issues.
• Fixes:
  1. Verify transfer syntax negotiation in logs; enable support for required syntaxes or request conversion in client.
  2. Check disk space and storage health: df -h and filesystem errors.
  3. Increase timeouts in Orthanc and sender client if transfers are large.
  4. Retry transfer with storescu to isolate client vs server problem.
  5. If corruption persists, enable Orthanc debug logging and inspect raw DICOM bytes.

5. Search/find returns incomplete or missing results

• Likely causes: metadata indexing issues, incomplete ingestion, database corruption, incorrect query parameters.
• Fixes:
  1. Confirm resources exist via REST API: GET /instances, /series, /studies.
  2. Rebuild or reindex metadata if using plugins or external databases (follow Orthanc docs for reindexing).
  3. Check Orthanc configuration for enabled plugins that alter indexing (Lua, Elasticsearch) and review their logs.
  4. Validate query parameters and matching rules (patient ID vs name, date ranges).
  5. Inspect Orthanc storage for orphaned files and run maintenance scripts if available.

6. Performance issues (high CPU, slow queries)

• Likely causes: large dataset, insufficient resources, heavy plugins (Elasticsearch), synchronous processing.
• Fixes:
  1. Monitor resources: top, iotop, vmstat.
  2. Increase RAM/CPU or move Orthanc to a more capable host or container limits.
  3. Offload search/indexing to Elasticsearch plugin or tune its settings; ensure Elasticsearch cluster is healthy.
  4. Enable caching where applicable and adjust Orthanc worker/thread settings.
  5. Profile slow operations via logs and consider asynchronous ingestion for heavy loads.

7. Plugin-related errors (Lua, REST, Elasticsearch)

• Likely causes: version mismatch, misconfiguration, plugin crashes.
• Fixes:
  1. Ensure plugin versions are compatible with your Orthanc version.
  2. Review plugin config blocks in Orthanc config and plugin-specific logs.
  3. Disable plugins one-by-one to isolate the failing plugin.
  4. Update or reinstall plugin; check for reported issues on the plugin repository.

8. Authentication/authorization failures (HTTP)

• Likely causes: wrong credentials, misconfigured HTTP headers, reverse-proxy altering auth headers.
• Fixes:
  1. Verify credentials in Orthanc config (Users block) or external auth provider settings.
  2. If using reverse proxy, ensure it forwards Authorization header: proxy_set_header Authorization $http_authorization;.
  3. Check token expiry and clock skew if using token-based auth (OAuth).
  4. Examine Orthanc logs for ⁄₄₀₃ details.

Quick diagnostic checklist (short)

• Check Orthanc logs and systemd journal.
• Verify service is running and port is reachable.
• Confirm AE titles, ports, and TLS settings for DICOM peers.
• Test DICOM transfers with DCMTK tools.
• Check disk space and permissions.
• Disable plugins to isolate issues.

If you want, provide your Orthanc version, relevant log excerpts, and config snippets and I’ll pinpoint likely causes and fixes.