DZI Deep Zoom Image Viewer failed or looks wrong? Troubleshooting guide
Troubleshoot extensions, file structure, dependencies, encoding, memory, and output error in DZI Deep Zoom Image Viewer while preserving the source.
Preserve the source first
Do not rename and overwrite the original, and do not treat a browser preview as the only acceptance record. Use a small copy and record size, producer, version, browser, and exact error.
The easy-to-miss fact for this format
If sample.dzi declares 256-pixel tiles, overlap 1, and 100000×60000 dimensions, sample_files/level/x_y.jpg must also be reachable; the XML alone is not the image.
Recommended troubleshooting order
- Test the page example or a smaller known-good file to confirm the tool runs.
- Check extension, signature, companion files, remote URL, and CORS; exclude a downloaded HTML error page.
- Supply the input again according to the workflow:
- Choose DZI XML or enter a public descriptor URL.
- Inspect Format, TileSize, Overlap, Width, and Height.
- Confirm the matching _files tile path is accessible.
- Zoom to check edges, seams, missing tiles, and top-level detail.
- Close memory-heavy tabs and retry in current Chrome or Edge.
- If it still fails, re-export from the producing application and validate in the receiving system.
Common questions and answers
Why is the canvas blank?
The _files directory may be inaccessible, paths may have wrong case, or CORS may block tiles.
Can it convert a large image to DZI?
No. The current tool is a viewer and does not generate pyramids.
Is the URL uploaded?
It is not saved; your browser requests the DZI and tiles directly.
Limits that must not be bypassed
- A local DZI file does not contain its tile directory
- Remote display depends on CORS and server access
- No DZI pyramid generation or missing-tile repair
Privacy handling
Local input is not uploaded to FreeTool for processing; remote IIIF/DZI URLs are requested by the browser from their source. Troubleshooting images, OCR text, model summaries, and converted files may contain sensitive or copyrighted content. De-identify and confirm rights before sharing.