Troubleshooting

Match the visible symptom, make the smallest change, and keep sensitive DICOM data out of public diagnostics.

The command is not found

Confirm that the package and interpreter agree:

python -m pip show dcmview-py
python -m dcmview_py --version

If the module works but dcmview does not, reopen the shell or add Python’s user scripts directory to PATH. Avoid installing repeated copies into different interpreters.

If the module cannot find a binary on an unsupported wheel platform, install a GitHub Release binary or source build and set DCMVIEW_BINARY to its absolute path.

A source build is missing a prerequisite

v0.2.12 source builds require Rust 1.88 or later, Node.js 20.19 or later, npm, CMake, and a C++ toolchain for the statically linked CharLS codec. ssh is needed only for tunnel-helper behavior.

rustc --version
node --version
npm --version
cmake --version

The Cargo build compiles and embeds the Svelte frontend. DCMVIEW_SKIP_FRONTEND_BUILD=1 is only valid when frontend/dist/index.html already exists.

No valid DICOM files are found

Check that the path exists and that the running user can read it. Directory scans recurse by default; remove --no-recursive if valid files live below the top level. Temporarily remove filters to distinguish unreadable input from readable-but-filtered objects.

DICOMDIR is deliberately skipped because v0.2.12 does not parse the file-set hierarchy. Point the viewer at the directory containing ordinary DICOM instances.

Files are skipped or filtered

The status bar and /api/files counters separate valid, skipped, and filtered objects. The bounded discovery ledger includes a stable reason for recent paths.

Skipped input can be non-DICOM, unreadable, malformed at required discovery metadata, or DICOMDIR. Filtered input is readable DICOM whose metadata did not satisfy every --filter predicate.

The viewer opens before every file appears

This is expected during progressive discovery. Wait until scan completion in the status bar. API automation should poll /api/files until scan_complete is true.

The port is already in use

Omit --port or pass zero to let the operating system choose:

dcmview --port 0 ./study

If an SSH command depends on a fixed port, choose another value in both the viewer and forwarding command.

The browser does not open

The server can still be healthy when the operating system browser launch fails. Use:

dcmview --no-browser ./study

Open the printed loopback URL manually. On a remote host, do not open the remote URL directly; follow the SSH forwarding guide.

An image reports unsupported transfer syntax

The object remains isolated and the viewer continues serving other files. Inspect its Transfer Syntax UID and compare it with v0.2.12 DICOM support.

Do not assume a browser can safely decode the original compressed fragment. dcmview requires a qualified server-side display path and returns a controlled 422 error for unsupported syntax.

Tags load but the image is missing

The object may be metadata-only, may lack Pixel Data, or may have an unsupported geometry, numeric precision, component layout, or photometric interpretation. Check the file’s support state and reason in Explorer or /api/files.

Metadata-only objects remain useful for tags and reference navigation. A no-pixel frame request returns 404; unsupported display/raw layouts return 422 or a request-scoped decode error.

A remote viewer is unreachable

Confirm all three addresses:

1. dcmview printed the expected remote loopback port.
2. The SSH command forwards to that exact remote port.
3. The browser opens the chosen local port.

Keep the remote server bound to 127.0.0.1. If a local port is busy, change only the first -L port and the local browser URL.

The built-in tunnel does not become ready

Confirm that ssh is on PATH, --tunnel-host is present, the destination accepts your authentication, and the chosen forwarded port is free. The helper can fail while the local loopback viewer remains useful; use manual forwarding for clearer SSH diagnostics.

VS Code opens a webview unexpectedly

New integrated terminals use bridge interception by default. Force one ordinary local launch:

export DCMVIEW_VSCODE_BYPASS=1
dcmview ./study

Or disable dcmview.terminalInterception.enabled and create a new terminal.

VS Code cannot start the viewer

Check dcmview: Show Bridge Status, then inspect dcmview.binaryPath. The extension otherwise tries the repository debug binary, its bundled platform binary, and PATH.

Verify that dcmview.extraArgs contains separate option/value elements and no stale paths. Increase dcmview.startupTimeoutSeconds only when the process is healthy but slow to report its URL.

On an unsupported platform, supply an absolute compatible binary path.

Annotation CSV fails to load

Confirm the required headers anon_dicom_path and ROI_coords. JSON-valued CSV cells must be quoted. Then check:

• [ymin, xmin, ymax, xmax] order and image bounds;
• zero-based frame indices below the frame count;
• matching counts for coordinates and frame lists; and
• num_ROI, when present, matching the coordinate count.

Path matching uses normalized absolute identity. Start dcmview from the expected directory when the CSV uses relative paths.

An invalid matching row prevents the CSV transaction from committing, but image viewing continues. Annotation reads and export report the import error.

Report issues safely

Use synthetic fixtures, redacted logs, and minimal reproduction steps. Do not attach DICOM files, screenshots, annotation CSVs, paths, patient/study identifiers, hostnames, or institutional metadata unless fully de-identified and approved for public sharing. Report suspected vulnerabilities privately.