How to Set Up a DICOM Server with dcm4che: Step-by-Step

Troubleshooting dcm4che — Common Problems & Fixes

1) Associations fail / “Failed to establish Association” or echo fails

• Cause: Wrong AE Title, port, host, or calling AET validation enabled.
• Fixes:
  • Verify AE Titles (both called and calling) match configuration.
  • Confirm TCP port (default 11112) and host are reachable (telnet/ss/netstat).
  • If association-rejection mentions hostname/IP, disable or update Validate Calling AE Hostname in Archive/AE settings or add the requestor’s IP/hostname to the AE’s DICOM Connections.
  • Check for duplicate AETs and change if necessary.

2) Connection refused / cannot connect to localhost but remote echos OK

• Cause: Listener not bound correctly, firewall, or service not running.
• Fixes:
  • Check server logs and startup lines for “Start TCP Listener on /0.0.0.0:11112”.
  • Ensure dcm4chee/dcm4che service is running (systemd/docker/wildfly).
  • Confirm no firewall/SELinux blocking and port is listening (ss -ltnp / netstat -plnt).
  • Verify device configuration uses correct host (0.0.0.0 vs localhost) and restart.

3) DICOM store/upload fails from viewers (HTTP 4xx/406) or uploader issues

• Cause: API/proxy mismatch, CORS, or incompatible client expectations after changes.
• Fixes:
  • Check viewer uploader configuration for correct dcm4chee endpoint (URLs, ports, HTTPS vs HTTP).
  • Inspect browser console / network responses for status code and message.
  • Ensure reverse proxy (nginx/traefik) forwards required headers and methods; enable CORS if needed.
  • Test with a CLI tool (storescu / curl) to isolate front-end vs server problem.

4) LDAP import / default-config.ldif errors

• Cause: Missing LDAP schema entries or import order wrong.
• Fixes:
  • Import LDIFs in order: init-baseDN.ldif → init-config.ldif → default-config.ldif → default-ui-config.ldif.
  • Use the LDAP server/version recommended in docs (ApacheDS/OpenDJ) and import required schema first.
  • Fix DN syntax issues in LDIF (ensure attribute names like dicomDeviceName are defined in schema).

5) Audit logging errors: “No compatible connection to AuditRecordRepository”

• Cause: Misconfigured Audit Logger device or disabled audit repository but logger still active.
• Fixes:
  • Verify AuditLogger and AuditRecordRepository device settings in LDAP/device config.
  • If disabling audit logging, ensure AuditLogger references are removed or auditInstalled=false on relevant devices.
  • Check logs for stack trace and correct device DN references.

6) Permission / file import errors and DB issues

• Cause: Wrong DB credentials, schema differences (MySQL vs PostgreSQL), or volume permissions in Docker.
• Fixes:
  • Confirm DB connection strings, user, schema migrations applied.
  • For Docker images, ensure persistent volumes are writable and container env vars match docs.
  • Inspect application logs for SQL errors and apply missing migrations or correct SQL dialect.

7) TLS / DICOM over TLS failures

• Cause: Missing/incorrect certs, wrong cipher or TLS settings.
• Fixes:
  • Verify keystore/truststore setup and that AE connections use expected TLS port.
  • Ensure certificate subject/hostnames match configuration or disable hostname validation for testing.
  • Check TLS protocol/cipher compatibility between peers.

8) Misc: configuration not applied after edits

• Cause: Changes not imported into LDAP or not reloaded by WildFly.
• Fixes:
  • Apply changes via the recommended LDIF or admin UI and restart services.
  • Use JMX/WildFly console to inspect AE/device settings and active connections.
  • Tail server logs on restart to confirm config load and listeners started.

Quick diagnostic checklist (run in this order)

1. Tail server log (wildfly/console) while reproducing the error.
2. Confirm service process/containers are running.
3. Verify network reachability: ping, telnet/ss/netstat.
4. Check AE Titles, ports, and DICOM Connections in device config.
5. Test with command-line DICOM tools (echoscu/storescu).
6. Inspect LDAP imports and DB connectivity.
7. Review proxy/TLS/CORS settings for HTTP-based uploads.

Useful commands

• Check listener: ss -ltnp | grep 11112
• Test AE echo: echotest (dcm4che tools) or echoscu aetitle@host:port
• View logs: journalctl -u-f or docker logs -f

If you want, I can create a short checklist tailored to your deployment (Docker, WildFly, or standalone) — specify which one.