How to Troubleshoot Common ezDICOM Errors QuicklyezDICOM is a lightweight DICOM viewer used by clinicians, radiologists, and students to view and manage medical images. While generally straightforward, users sometimes encounter errors that interrupt workflow. This guide walks through the most common ezDICOM issues, explains likely causes, and gives step‑by‑step troubleshooting actions so you can restore functionality quickly.
Quick checklist before you start
- Restart ezDICOM and your computer — many transient problems resolve with a restart.
- Confirm you have the latest ezDICOM version — check the official distribution site or your organization’s software portal.
- Check file sources and integrity — corrupt or partially downloaded DICOM files cause viewer errors.
- Verify system requirements — ensure CPU, RAM, GPU (if used), and OS match ezDICOM’s published needs.
1. Installation and startup errors
Symptoms: ezDICOM fails to install, installer crashes, app won’t launch, or startup freezes.
Likely causes:
- Missing system libraries or dependencies.
- Corrupted installer.
- Insufficient user permissions.
- Antivirus or security software blocking installation or launch.
Troubleshooting steps:
- Re-download the installer from a trusted source to rule out corruption.
- Run installer as administrator (Windows) or with elevated privileges (macOS/Linux sudo).
- Temporarily disable antivirus or add ezDICOM to the allowlist, then reinstall.
- Check OS event logs (Windows Event Viewer / macOS Console / syslog) for error messages referencing missing DLLs or permission failures.
- On Windows, ensure Visual C++ redistributables and .NET frameworks (if required) are installed. On Linux, check for required shared libraries and correct versions.
- If the app opens but immediately crashes, start it from a terminal/command line to capture stdout/stderr messages, then share the logs with IT or support.
When to escalate: If system logs show missing proprietary libs you can’t install, or installer fails on multiple machines, contact ezDICOM support with installer version, OS version, and logs.
2. DICOM file won’t open or “unsupported format” errors
Symptoms: File doesn’t load, displays “unsupported format,” blank canvas, or corrupted image artifacts.
Likely causes:
- File is not a valid DICOM or uses uncommon/private tags/transfer syntaxes.
- File is truncated or corrupted.
- Transfer syntax (e.g., JPEG2000, RLE, or deflated transfer syntax) not supported or requires codec.
Troubleshooting steps:
- Verify file with a DICOM validator (e.g., dcm2xml, DicomBrowser) to confirm it’s a proper DICOM file.
- Try opening the file in an alternative viewer (e.g., RadiAnt, Horos, OsiriX, MicroDICOM) to determine whether the file or ezDICOM is the problem.
- If alternate viewers open it, note the transfer syntax and codec. Install necessary codecs or enable support in ezDICOM if available.
- For truncated files, attempt to obtain a fresh copy from PACS or the original imaging modality.
- If private tags are used, request a DICOM with private elements removed or standardized, or ask the originating site to export in a common transfer syntax (e.g., Explicit VR Little Endian).
Tip: When diagnosing, keep a copy of a failing file and the output of a DICOM dump (headers) to speed support interactions.
3. Slow performance or high memory/CPU usage
Symptoms: Sluggish scrolling through image stacks, long load times, UI freezes, or high RAM/CPU/GPU usage.
Likely causes:
- Large multi-frame studies or high-resolution images (e.g., whole‑slide images).
- Inadequate hardware resources.
- Renderer using CPU instead of GPU (or vice versa) inefficiently.
- Background processes (antivirus, indexing, backup) competing for resources.
Troubleshooting steps:
- Close other applications to free memory and CPU.
- Reduce image load: open single series instead of entire study, or load fewer images at a time.
- Check ezDICOM settings for image caching, downsampling, or hardware acceleration options—enable GPU acceleration if available and supported by your GPU drivers.
- Update graphics drivers and OS. On Windows, use manufacturer drivers (NVIDIA/AMD/Intel) rather than generic drivers.
- Monitor system resource use with Task Manager (Windows) or Activity Monitor (macOS) to identify competing processes.
- If using network storage or PACS, test loading from a local copy to separate network latency from viewer performance.
When to escalate: If performance is poor despite adequate hardware and local files, gather a profiler log or performance trace for developer support.
4. PACS connectivity and network transfer errors
Symptoms: Cannot query/retrieve studies, timeouts, failed associations, or missing patient/study lists.
Likely causes:
- Incorrect AE Title, host, port, or transfer syntax mismatch.
- Network firewall or VPN blocking DICOM ports (usually 104, or custom ports).
- PACS requiring TLS/secure DICOM (DICOMweb/WADO or DICOM over TLS) while ezDICOM is configured for plain DICOM.
- AE Title or IP authorization restrictions at PACS.
Troubleshooting steps:
- Verify AE Title, IP/hostname, and port match the PACS configuration. Confirm with PACS admin.
- Test network connectivity: ping / traceroute to the PACS host; use telnet or nc to test the DICOM port.
- Confirm whether the PACS requires DICOM over TLS, DICOMweb (WADO/REST), or C-STORE SCP specifics; ensure ezDICOM is set to the correct mode.
- Check firewall rules on local machine and network; work with IT to allow required ports and DICOM traffic.
- Review logs for association negotiation errors—look for refused transfers due to unsupported transfer syntaxes or AE Title rejection.
- Try a DICOM testing tool (e.g., DCMTK storescu/findscu) to reproduce the issue and isolate if it’s the viewer or network/PACS side.
Tip: Provide PACS admins with the exact association request and error codes from ezDICOM logs to speed resolution.
5. Windowing, orientation, and display artifacts
Symptoms: Incorrect brightness/contrast, flipped or rotated images, garbled pixels or banding artifacts.
Likely causes:
- Window/level presets not applied or incorrectly read from DICOM tags.
- Image orientation tags (Image Orientation Patient, Image Position Patient) misinterpreted.
- Color palette or photometric interpretation mismatch (e.g., MONOCHROME1 vs MONOCHROME2).
- Lossy compression artifacts in exported images.
Troubleshooting steps:
- Adjust window/level manually to confirm image data is present and not all-zero.
- Inspect DICOM header tags for Photometric Interpretation, Samples per Pixel, and Pixel Representation. If Photometric is MONOCHROME1 but viewer expects MONOCHROME2, invert the display.
- For rotated/misaligned images, verify Image Orientation Patient and Image Position Patient tags; if those tags are missing or incorrect, request corrected export from the modality.
- If banding or block artifacts are visible, check whether the image was lossy‑compressed; ask for lossless export for diagnostic quality.
- Compare the same image in another viewer—if artifact persists, file is likely the problem.
6. Annotation, measurement, or export problems
Symptoms: Annotations not saving, measurements incorrect, exported images missing overlays or metadata.
Likely causes:
- Read‑only file or insufficient permissions to write annotation files/settings.
- Annotations stored locally in a user profile that is not being saved or is blocked by OS/IT policies.
- Export function defaults exclude overlays or burn-in is disabled.
Troubleshooting steps:
- Confirm you have write permission to the directory where ezDICOM saves annotations or user settings.
- Check ezDICOM settings for annotation storage location (local vs. database/PACS).
- If annotations need to be sent back to PACS, confirm whether ezDICOM supports SCU Storage of Structured Reports or Presentation States and that PACS accepts those SOP classes.
- For incorrect measurements, ensure pixel spacing and slice thickness tags are present and read correctly; measurement errors often stem from missing or wrong spatial metadata.
- When exporting, enable “burn overlays” or “include annotations” if available, or export a DICOM secondary capture that preserves displayed overlays.
7. Licensing, registration, and feature access issues
Symptoms: Features disabled, licensing errors, reminders to register, or trial expired messages.
Likely causes:
- License file missing, expired, or mismatched with machine ID.
- Time/date mismatch on system causing license validation failure.
- Trial limits reached.
Troubleshooting steps:
- Verify system date and time are correct; correct clock skew can invalidate license checks.
- Confirm license file or key is installed correctly and matches the expected machine identifier.
- If license requires activation by an external server, ensure outbound connections for activation are allowed.
- Contact your license administrator or ezDICOM vendor with the license ID and error text for re-issuance.
8. Error logs: how to collect and what to include
What to collect:
- ezDICOM application logs (enable verbose/debug mode if available).
- A copy of a failing DICOM file (or a small sample that reproduces the issue).
- System information: OS version, ezDICOM version/build, CPU/GPU model, RAM.
- Steps to reproduce the error and exact timestamps.
- Screenshots of error dialogs and relevant parts of the DICOM header (Patient ID, Study/Series UID redacted if needed).
How to collect:
- Launch ezDICOM from the command line to capture console output if the app doesn’t produce explicit logs.
- Use DICOM tools (dcmdump, dcm2xml) to export headers.
- Use OS tools to capture crash dumps if the application crashes.
Provide these artifacts to support to reduce back-and-forth and speed resolution.
9. Preventive measures and best practices
- Keep ezDICOM and system libraries up to date.
- Standardize on common transfer syntaxes (Explicit VR Little Endian, Implicit VR Little Endian) within your organization when possible.
- Maintain a known-good set of DICOM test files for troubleshooting.
- Configure network and firewall rules proactively for PACS communication.
- Train staff on export settings at modalities to avoid lossy or non‑standard DICOM exports.
10. When to contact ezDICOM support or IT
Contact support when:
- Errors persist after basic troubleshooting and you can reproduce them reliably.
- You can supply logs, a sample failing file, and system information.
- The issue affects multiple users or machines (likely a network, PACS, or build issue).
If it’s a site-specific network/PACS configuration, work with your IT and PACS administrators first to verify AE Titles, ports, and firewall rules before escalating to vendor support.
If you want, I can:
- Provide a troubleshooting checklist you can print and keep by workstations.
- Draft an email template to send to IT or ezDICOM support including the logs and files they’ll need.
Leave a Reply