Troubleshooting

Troubleshooting#

A slide will not open#

  1. Confirm that the path is correct and readable.

  2. Open the file with zs.open_wsi(path) in a minimal Python session to isolate reading from the analysis pipeline.

  3. Install a reader that supports the format.

  4. Test another file from the same scanner.

  5. Check whether the file is truncated, encrypted, or stored on an unavailable mount.

See supported readers and formats.

MPP is missing or wrong#

Do not infer MPP solely from the filename or nominal magnification. Retrieve it from scanner metadata or acquisition records. When the source MPP is known, override it during tiling:

zs.pp.tile_tissues(wsi, 256, mpp=0.5, slide_mpp=0.25)

Record the override in the analysis manifest.

No tissue or no tiles are found#

Visualize each intermediate result. Compare tissue methods, lower minimum-area thresholds, and confirm tile field of view. For tiling, temporarily disable background filtering to determine whether geometry or coverage filtering is responsible:

zs.pp.tile_tissues(wsi, 256, mpp=0.5, background_filter=False)

A model cannot be downloaded#

Check the model identifier, internet access, Hugging Face authentication, gated-model approval, disk quota, and HF_HOME. On offline nodes, pre-populate the cache and set HF_HUB_OFFLINE=1.

Inference runs out of memory#

Reduce batch_size, then reduce num_workers. Enable mixed precision on supported hardware, select a smaller model, or process fewer tiles. Restart the process after an out-of-memory error if the framework has retained allocations.

A key is not found#

Inspect the object instead of guessing:

print(list(wsi.shapes))
print(list(wsi.tables))
print(list(wsi.images))

Remember that feature tables usually include the tile key as a suffix, such as uni_tiles. Check the output-key reference.

Feature and tile row counts do not match#

Feature rows correspond to the tile table used during extraction. This mismatch usually means that the tile table was filtered or replaced afterward, or the wrong tile_key was selected. Regenerate features from the current tiles or restore the matching tile table; do not truncate arrays to force equal lengths.

Annotations are shifted, scaled, or mirrored#

Confirm that coordinates are level-0 pixels, check slide bounds and MPP, and verify whether the source tool uses a bounded-image origin. Test in_bounds on a new key and compare several known landmarks. NDPA also requires valid Hamamatsu offsets and MPP metadata.

A plot is blank#

Plot the underlying shapes without feature coloring. Then verify the selected tissue, tile, feature, and color keys; zoom bounds; value range; and annotation coordinate system. Add options back one at a time.

Results differ between runs#

find_tissues(level="auto") can select a level based on available memory. Set a fixed level for repeatability. Also record package versions, model weight revisions, device, precision, random seeds, and all preprocessing parameters.