How to troubleshooting archive previewer
- Step 1Check the file size against your tier — Free blocks anything over 50 MB before parsing; Pro over 500 MB; Pro + Media / Developer over 2 GB. An 'exceeds the … tier per-job limit' message means trim, split, or upgrade.
- Step 2Check the entry count — Free allows 500 entries, Pro 50,000, Pro + Media / Developer 500,000. Tiny-file-heavy archives can blow the entry cap while under the size cap.
- Step 3Confirm the format is supported — Supported: ZIP, TAR, GZIP, 7Z, RAR, BZIP2, XZ, ISO. A
Could not detect or extract archive formaterror means the magic bytes matched nothing — usually a truncated download. - Step 4If it's 7Z/RAR and it stalls or errors — These use the libarchive WASM bridge. A WebAssembly-blocking extension or a header-encrypted 7Z is the usual cause; try a clean browser profile or supply the file to the extractor instead.
- Step 5If the output looks 'wrong', confirm it's by-design — Compressed = Size for non-ZIP and only 200 files in the table are expected behaviours, not failures. The tree and header count are complete.
- Step 6Route to the right tool if previewing isn't enough — To extract use multi-format-extractor; to repair a broken ZIP use corrupted-zip-repair; to verify soundness use archive-integrity-tester.
Symptom → cause → fix
Ordered by how often each one is the culprit. 'Blocked before parse' means no bytes were read; 'parse failed' means the file was read but couldn't be decoded.
| Symptom | Likely cause | Fix |
|---|---|---|
| 'Exceeds the free/pro tier per-job limit' | File over 50/500/2048 MB cap | Trim or split the archive, or upgrade tier |
| Won't preview a huge tiny-file archive | Over the entry cap (500/50k/500k) | Upgrade, or list a subset with selective tools |
| 'Could not detect or extract archive format' | Magic bytes match nothing — usually truncated | Re-download; verify with archive-integrity-tester |
| 7Z/RAR stalls or errors, ZIP works fine | WASM blocked, or header-encrypted 7Z | Clean browser profile; or supply password via extractor |
| Compressed column equals Size | Non-ZIP format (by design) | Use compression-ratio-calculator for real ratios |
| Only 200 files listed in the table | Table cap (by design) | Tree shows all; use file-listing-generator for full list |
| Timestamps all identical on a TAR/7Z | Fallback to archive file date (by design) | ZIP shows real per-entry times; verify after extract |
| Encrypted ZIP still lists names | Central-directory names are in the clear (by design) | Expected — no password needed to preview ZIP |
Tier limits for the Archive Previewer
Per-job limits enforced before parsing. The previewer reads one archive at a time, so the batch column matters less here than the per-file size and the per-archive entry cap. Numbers are the live values from the archive tier-limit table.
| Tier | Max file size | Max entries / archive | Files per job | Notes |
|---|---|---|---|---|
| Free | 50 MB | 500 entries | 1 | Enough for a release ZIP or a Finder-zipped folder. Larger archives prompt an upgrade before any bytes are read. |
| Pro | 500 MB | 50,000 entries | 20 | Covers most CI artifacts and node_modules snapshots. Entry cap, not size, is usually the first wall on monorepo ZIPs. |
| Pro + Media | 2 GB | 500,000 entries | 100 | For dataset bundles and disk-image-sized archives. |
| Developer | 2 GB | 500,000 entries | unlimited | Same ceilings as Pro + Media with unlimited files per job for scripted runs via the runner. |
Behaviours that are not bugs
These surprise people but are correct given how the previewer works. Knowing them saves a wasted bug hunt.
| Observation | Why it happens | What to use instead if you need more |
|---|---|---|
| Compressed = Size on 7Z/TAR/GZIP | Real compressed size is read only from a ZIP central directory | compression-ratio-calculator |
| Method column blank on non-ZIP | Per-entry method comes from the ZIP central directory only | ZIP previews show method natively |
| Table stops at 200 files | Flat table is capped for render performance | file-listing-generator (full CSV/JSON) |
| All non-ZIP timestamps identical | Falls back to the archive file's last-modified date | Extract then read true mtimes; ZIP shows real times |
| No options / settings to change | The previewer has zero configuration by design | selective-extractor for glob filtering |
| Encrypted ZIP names visible | ZIP stores names in the clear even when data is encrypted | multi-format-extractor to unlock data |
Cookbook
Walk these in order — each pins a symptom to a concrete check and the next action.
Diagnose a size-limit block
The error names the limit and your tier. Nothing was parsed — the size gate runs first.
Error:
File "dataset.zip" exceeds the free tier per-job
limit (50.0 MB). Upgrade for larger files.
Check: dataset.zip is 640 MB.
Fix: Pro → 500 MB, Pro + Media/Developer → 2 GB,
or split the archive before previewing.Diagnose an unrecognised format
Magic bytes matched no known signature. A truncated or partial download is the most common reason.
Error:
Could not detect or extract archive format for x.7z
Check: ls -l x.7z → 2 KB (expected 240 MB)
→ download was truncated.
Fix: Re-download fully, then re-run. Confirm with
archive-integrity-tester if unsure.7Z works elsewhere but stalls here
ZIP previews fine but 7Z hangs — that isolates the problem to the libarchive WASM path.
Symptom: .zip lists instantly; .7z spins forever.
Check: Browser console for a WebAssembly error or a
blocked-resource message (ad/script blocker).
Fix: Disable the blocker for this site or try a
clean browser profile, then retry the 7Z."Compression looks wrong" — it isn't
Compressed equals Size on a TAR. That's expected: only ZIP exposes a real compressed size.
Observed (logs.tar.gz): Name Size Compressed Method app.log 28.6 MB 28.6 MB (blank) Not a bug: non-ZIP entries report uncompressed size in both columns. For real ratios use compression-ratio-calculator.
"Half my files are missing" — check the tree
The table shows 200 rows but the archive has thousands. The tree and header count are complete.
Header: big.zip — 9,830 entries (ZIP) Table: shows 200 rows (largest by size) Not missing — the table is capped at 200. The tree lists every entry. For a full export of all 9,830, run file-listing-generator (CSV or JSON).
Edge cases and what actually happens
File over the tier size cap
Blocked (limit)Free 50 MB, Pro 500 MB, Pro + Media / Developer 2 GB. The check runs before parsing, so nothing is read. Trim, split, or upgrade — the error states the exact cap and tier.
Entry count over the tier cap
Entry capFree 500, Pro 50,000, Pro + Media / Developer 500,000 entries per archive. A folder of thousands of tiny files hits this even when small in bytes. Upgrade, or preview a subset created with a selective tool.
Unrecognised / corrupt header
Invalid formatIf the first eight bytes match no supported signature, the previewer makes a best-effort ZIP attempt and otherwise errors with Could not detect or extract archive format. Truncated downloads are the top cause; re-download and verify with archive-integrity-tester.
Header-encrypted 7Z
May failSome 7Z archives encrypt the header itself, so listing requires the password; libarchive can't enumerate without it and the preview fails. ZIP headers stay readable regardless. To open it, use multi-format-extractor with the password.
7Z/RAR hangs while ZIP works
WASM blockedZIP/TAR/GZIP use fflate; 7Z/RAR/BZIP2/XZ/ISO use the libarchive WASM bridge. If only the latter fail, a WebAssembly-blocking extension or strict CSP is the usual cause. Try a clean browser profile or allowlist the site.
Compressed equals Size
By designReal per-entry compressed size is read only from a ZIP central directory. Non-ZIP entries report uncompressed length in both columns. For genuine ratios use compression-ratio-calculator.
Only 200 files in the table
ExpectedThe flat table is capped at the 200 largest files for performance; the tree renders every entry and the header shows the true count. For a complete listing use file-listing-generator.
Identical timestamps on a non-ZIP archive
By designOnly ZIP carries per-entry DOS date/time in the central directory. For TAR/7Z/GZIP the previewer falls back to the archive file's date for every entry. Read true mtimes after extraction if you need them.
No settings panel appears
ExpectedThe previewer has zero options by design — drop one archive and press Process. If you wanted to filter, sort, or limit depth, those live in sibling tools like selective-extractor and nested-archive-extractor.
Encrypted ZIP shows filenames
PreservedZIP stores entry names in the clear in the central directory even when data is AES-256/ZipCrypto encrypted, so names list without a password. This is expected and not a leak — only file data is protected.
Frequently asked questions
Why won't my large archive preview?
It's over your tier's size cap: 50 MB on Free, 500 MB on Pro, 2 GB on Pro + Media and Developer. The check runs before any parsing, so you'll see an 'exceeds the … tier per-job limit' message and nothing is read. Trim or split the archive, or upgrade. Separately, a tiny-file-heavy archive can exceed the per-archive entry cap (500 / 50,000 / 500,000) even when small in bytes.
It says 'Could not detect or extract archive format' — what now?
The first eight bytes matched no supported signature (ZIP, GZIP, BZIP2, XZ, 7Z, RAR, TAR). The most common reason is a truncated or partial download — check the file size against what you expected. Re-download fully and retry; if you still suspect damage, run archive-integrity-tester.
Why does it stall only on 7Z or RAR?
ZIP, TAR, and GZIP are handled by fflate; 7Z, RAR, BZIP2, XZ, and ISO go through the libarchive WebAssembly bridge. If only those formats hang or error while ZIP works, a WASM-blocking browser extension, an aggressive content blocker, or a strict CSP is usually responsible. Try a clean browser profile or allowlist the site. A header-encrypted 7Z is the other cause — that needs a password to even list.
Is 'Compressed equals Size' a bug?
No. The previewer reads a real per-entry compressed size only from a ZIP central directory. For 7Z, RAR, TAR, and GZIP it enumerates entries and reports the uncompressed length in both the Size and Compressed columns. If you need true compressed-vs-original figures for a non-ZIP archive, use compression-ratio-calculator.
Where did the rest of my files go — I only see 200?
The flat table is capped at the 200 largest files by size for render performance. It's not dropping data: the folder tree above the table renders every entry, and the header line reports the true total count. For a complete machine-readable list of all entries, run file-listing-generator for CSV, JSON, or a full text tree.
Why are all my timestamps the same?
On non-ZIP archives the previewer doesn't surface per-entry times and falls back to the archive file's own last-modified date for every entry. ZIP is the exception — it decodes each entry's real DOS date/time from the central directory. If you need accurate per-file times for a TAR or 7Z, read them after extraction.
Do I need the password to preview an encrypted archive?
Not for ZIP — entry names are stored in the clear in the central directory even when the file data is encrypted, so the tree and table render and each encrypted entry just carries a flag. No password is requested because ZIP data is never decompressed here. A header-encrypted 7Z is different and may need the password to list. To unlock and extract data, use multi-format-extractor.
There are no options — am I missing a settings panel?
No — the previewer has zero configuration by design. You drop one archive and press Process. If you wanted to filter by glob, sort differently, generate a CSV listing, or limit recursion depth, those are separate tools: selective-extractor, file-listing-generator, and nested-archive-extractor.
The preview is empty — '(empty archive)'. Why?
The archive genuinely has no file entries (only directories, or nothing), or for a non-ZIP format every entry was a directory that the enumerator filtered out. Confirm the source actually contains files; a freshly created or wrongly built archive can be empty. Re-create it and re-preview.
Can I preview a file with the wrong or no extension?
Yes. Format detection uses the first eight magic bytes, not the file extension. A ZIP renamed data.bin, an extension-less download, or a .docx (which is a ZIP) all preview correctly. Only the byte signature matters, so a wrong extension never breaks the preview by itself.
Does the previewer extract or decompress my archive?
For ZIP, no. It reads only the central directory — the index ZIP keeps at the end of the file — so a 1 GB ZIP with 50,000 entries lists in well under a second because no compressed bytes are touched. For every other format (7Z, RAR, TAR, GZIP, BZIP2, XZ, ISO) it must decode the whole archive in memory to enumerate entries, because those containers have no detached index a browser can parse. Nothing is written to disk and nothing is uploaded either way.
Why is the Compressed column equal to the Size column for my 7Z or TAR?
Because the previewer only has the real per-entry compressed size for ZIP, which it reads straight from the central directory. For 7Z, RAR, TAR, GZIP and the libarchive-handled formats it decodes the entries and reports the uncompressed byte length in both columns. So treat the Compressed column as meaningful for ZIP only. If you need true compressed-vs-original numbers for a non-ZIP archive, use compression-ratio-calculator.
Are timestamps in the tree accurate?
For ZIP, yes — each entry's DOS date/time is decoded from the central directory. For non-ZIP formats the previewer does not surface per-entry timestamps; it falls back to the archive file's own last-modified date for every entry. To normalise or inspect ZIP timestamps specifically, see timestamp-normalizer.
Can it preview password-protected archives?
For ZIP, yes — filenames in a ZIP central directory are stored in the clear even when the file data is AES-256 or ZipCrypto encrypted, so the tree and table render fine and the entry simply shows an encryption flag. The previewer never asks for or needs the password because it does not decompress ZIP data. Encrypted 7Z/RAR that libarchive cannot open without a password may fail to enumerate. To actually unlock and pull files, use multi-format-extractor.
Why did a .tar.gz take far longer than a same-size ZIP?
ZIP lists from its central directory with no decompression, so it's near-instant regardless of size. A .tar.gz (or 7Z/RAR) has no detached index a browser can read, so the previewer must fully decode the archive in memory to enumerate entries — that's inherently slower and uses more memory on large files. It's expected, not a stall, but a very large non-ZIP archive can be the slow case.
Privacy first
Every JAD Archive tool runs entirely in your browser using fflate, @zip.js/zip.js, and the libarchive WASM bridge. Your archives never leave your device — verified by zero outbound network requests during processing.