How to troubleshooting the filename sanitiser
- Step 1Confirm the file is actually an archive — The tool detects format from magic bytes. If you renamed a non-archive to
.zip, detection fails. Test the file first with archive-integrity-tester. - Step 2Check size and entry count against your tier — Free is 50 MB and 500 entries. A 5 MB ZIP with 600 files still fails on the entry cap. Compare both numbers before assuming a bug.
- Step 3Rule out encryption — If the ZIP is password-protected, the Sanitiser can't read it — it passes no password. Decrypt it elsewhere, then sanitise.
- Step 4If it's 7z/RAR/bz2/xz, verify WebAssembly works — Those formats need the libarchive WASM module. A browser extension or policy blocking
wasmmakes them fail while ZIP/GZIP/TAR still work. - Step 5Compare entry counts in vs out — If a file seems missing from the output, two source names probably collapsed to the same safe name and one overwrote the other. The result panel's
Entriescount reveals this. - Step 6Remember the output is ZIP — If you fed a 7z and got a ZIP, that's correct behaviour, not an error. To keep the original container, convert afterwards with archive-format-converter.
Symptom to cause to fix
The failure modes the tool can actually produce, mapped to their real cause and the concrete fix.
| Symptom | Real cause | Fix |
|---|---|---|
Could not detect or extract archive format | Magic bytes match no known format, or file is truncated/non-archive | Verify it's a real archive; test with archive-integrity-tester |
| File rejected before processing | Over the tier size or entry-count cap | Upgrade tier or reduce the archive |
| 7z/RAR fails but ZIP works | libarchive WASM blocked by extension/policy | Allow WebAssembly, or convert the format first |
| Encrypted ZIP won't open | No password is passed to the reader | Decrypt first, then sanitise |
| A file is missing from the output | Two names collapsed to one; later overwrote earlier | Compare in/out entry counts; rename source entries |
| Got a ZIP, expected a 7z/tar | Writer only outputs ZIP | Convert after, via archive-format-converter |
| A device-named file still fails on Windows | Name is COM5+/LPT3+ (outside the covered set) | Rename manually; only COM1–4/LPT1–2 are escaped |
Tier caps (so you can tell a limit from a bug)
If your file is rejected, check it against both columns — the entry cap is enforced independently of size.
| Tier | Max size | Max entries | Files / run |
|---|---|---|---|
| Free | 50 MB | 500 | 1 |
| Pro | 500 MB | 50,000 | 20 |
| Pro-media | 2 GB | 500,000 | 100 |
| Developer | 2 GB | 500,000 | unlimited |
Cookbook
Each block shows the symptom you see, then the diagnosis and fix.
Diagnose a format-detection error
The most common hard error. The tool reads the first bytes to detect ZIP/GZIP/TAR/7z/RAR/bz2/xz; if none match and a last-resort ZIP parse also fails, it throws.
Symptom: Error: Could not detect or extract archive format for data.zip Diagnosis: data.zip is actually an HTML error page renamed to .zip (downloaded behind a login wall) Fix: Re-download the real archive; confirm with archive-integrity-tester
A file vanished — name collision
Two distinct names that sanitise to the same safe name share one output key; the second overwrites the first. The output simply has one fewer entry than the input.
Input entries: a:b.txt -> a_b.txt a*b.txt -> a_b.txt (same!) Result: Entries: 1 (one file lost) Renames: 2 Fix: Rename the source entries so they differ, then re-sanitise
Encrypted ZIP refuses to open
The reader is invoked without a password, so an encrypted entry can't be decrypted and the run errors.
Symptom: extraction fails on secret.zip Cause: secret.zip is AES/ZipCrypto encrypted Fix: decrypt it first (e.g. in 7-Zip), then sanitise the plain ZIP
7z fails, ZIP works — WASM blocked
ZIP/GZIP/TAR use pure-JS fflate; 7z/RAR/bz2/xz need libarchive WASM. If WebAssembly is blocked, only the exotic formats fail.
Observation: project.zip -> sanitises fine project.7z -> fails to read Diagnosis: an extension or enterprise policy blocks wasm Fix: allow WebAssembly for the site, or unpack the 7z first
Expected a 7z back, got a ZIP
Not a bug. The Sanitiser always writes ZIP. The contents and names are correct; only the container changed.
Input: release.7z Output: release-sanitized.zip <- always ZIP To keep 7z: sanitise here, then archive-format-converter (libarchive is read-only in-browser, so true 7z writing isn't done here)
Edge cases and what actually happens
File over the tier size cap
413 rejectedFree 50 MB, Pro 500 MB, Pro-media/Developer 2 GB. A file above your tier's cap is rejected before any processing. Upgrade or shrink the archive.
Archive over the entry-count cap
Entry limit rejectedFree 500 entries, Pro 50,000, Pro-media/Developer 500,000. This is independent of size — a small ZIP with thousands of tiny files still fails. Split it or upgrade.
Non-archive file renamed to .zip
Detection errorDetection uses magic bytes, not the extension. An HTML page or text file renamed to .zip throws Could not detect or extract archive format. Confirm the real file type.
Encrypted ZIP
Read errorNo password is supplied to the reader, so encrypted archives can't be opened. Decrypt first. The tool never produces encrypted output either — see encrypted-zip-creator for that.
WebAssembly blocked
WASM error7z, RAR, bzip2, xz rely on libarchive WASM. If a browser extension or policy blocks wasm, those formats fail while ZIP/GZIP/TAR keep working. Allow WebAssembly or pre-convert.
Name collision drops a file
Last write winsIf two source names sanitise to the same safe name, the later entry overwrites the earlier, so the output has one fewer entry. Compare in/out Entries counts to detect it.
Output container is ZIP, not the source format
By designThe writer only emits ZIP. Getting a .zip from a .7z input is expected. Convert afterwards with archive-format-converter if you need the original format.
A device-named file still fails on Windows
Known gapOnly CON, PRN, AUX, NUL, COM1–4, LPT1–2 are prefixed. A file named COM9 or LPT5 isn't escaped and Windows will still refuse it. Rename it manually.
Reference inside a file is now stale
Manual fixupSanitising rewrites names but never file contents. A manifest or config that points at a renamed entry needs a manual update afterwards.
Tool seems stuck on a huge archive
ProcessingReading a large 7z/RAR through WASM and re-zipping is CPU- and memory-bound in your browser. A near-cap archive can take a while; it isn't frozen. If it truly hangs, the file may be at the memory limit — try a smaller one or a higher tier.
Frequently asked questions
Why do I get 'Could not detect or extract archive format'?
The tool detects format from the file's magic bytes. If the bytes match no known format (ZIP/GZIP/TAR/7z/RAR/bz2/xz) and a fallback ZIP parse also fails, it throws this. Usually the file isn't really an archive — e.g. an HTML error page downloaded behind a login and saved with a .zip extension. Re-download or verify with archive-integrity-tester.
Why was my file rejected before it even processed?
It's over your tier's size or entry-count cap. Free allows 50 MB and 500 entries; Pro 500 MB / 50,000; Pro-media and Developer 2 GB / 500,000. The entry cap is checked separately, so a small but file-heavy archive can fail on count alone.
Why does a 7z fail when ZIPs work fine?
ZIP, GZIP, and TAR are handled by pure-JS fflate. 7z, RAR, bzip2, and xz need a libarchive WebAssembly module. If a browser extension or enterprise policy blocks wasm, those formats fail while ZIP keeps working. Allow WebAssembly for the site or unpack the format first.
Why won't it open my password-protected ZIP?
The Sanitiser calls the reader without a password, so it can't decrypt entries — the run errors. Decrypt the archive elsewhere (e.g. in 7-Zip) and then sanitise the plain ZIP.
A file disappeared from the output — is that a bug?
Almost certainly a name collision. If two distinct names sanitise to the same safe name (e.g. a:b.txt and a*b.txt both become a_b.txt), they share one output key and the later one overwrites the earlier. The output Entries count will be lower than the input. Rename the source entries so they differ, then re-run.
I fed a 7z and got a ZIP — why?
That's by design. The tool reads many formats but only ever writes ZIP (via fflate). The names and contents are correct; just the container changed. To keep the original format, sanitise here then convert with archive-format-converter.
A file named COM9 still fails on Windows after sanitising — why?
The reserved-name escaping covers CON, PRN, AUX, NUL, COM1–COM4, and LPT1–LPT2 only. Higher device numbers like COM9 or LPT5 aren't prefixed, so Windows still refuses them. Rename those manually.
Does sanitising change my file contents?
No. Only entry names are rewritten; the decompressed bytes are identical. The one consequence: if another file (a manifest, config, or signature) references an entry by its old name, that reference is now stale and needs a manual fix.
Why is a single dot in my filename left alone but a double dot changed?
Only runs of two or more dots collapse to _ (that's the anti-traversal rule). A single dot — normal extensions like .txt or .tar.gz — is preserved. So app.min.js is untouched, but app..js becomes app_js.
The tool seems frozen on a big archive — what's happening?
Reading a large 7z/RAR through WASM and re-zipping is CPU- and memory-intensive and runs entirely in your browser tab. A near-cap file can take real time without being stuck. If it genuinely hangs, you may be at the browser's memory limit — try a smaller file or a higher tier.
Can I sanitise several archives at once to save time?
No — the tool takes one file per run. There's no batch or folder input. Run them one at a time, or script the JAD runner to iterate. (Archive tools have no REST API, so automation is via the headless-browser runner.)
Which tool should I use if the Sanitiser is the wrong fit?
To strip a leading folder use path-prefix-remover; to remove empty directories use empty-folder-pruner; to just inspect names use file-listing-generator or archive-previewer. The Sanitiser only fixes unsafe characters, traversal, and reserved names.
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.