How to troubleshooting format converter
- Step 1Read the error message verbatim — The tool throws specific text. 'GZIP target supports a single file only' means multi-file + gz. 'appears to be encrypted' means a password-protected 7z/rar/zip. 'libarchive WASM extraction failed' means a WASM/worker issue. Match the message first.
- Step 2Check the target vs the input shape — If you chose
gz, confirm the input archive has exactly one entry. If not, switchtargetFormattotar.gz, which bundles many files into one compressed stream. - Step 3Check the file against your tier — Free allows 50 MB and 500 entries. Confirm both — a small archive with 600 tiny files still exceeds the entry cap. Pro is 500 MB / 50,000; Pro-media and Developer are 2 GB / 500,000.
- Step 4Rule out encryption — If the input is a password-protected 7z/rar/zip, the conversion cannot proceed — there is no password field and libarchive rejects encrypted entries. Decrypt locally first, then convert the plaintext archive.
- Step 5Rule out a WASM block — If only 7z/rar/bz2/xz inputs fail (ZIP/GZIP/TAR work), a browser extension or policy is likely blocking WebAssembly. Allowlist the page, disable the extension, or use a different browser.
- Step 6Verify the output — Once it converts, confirm with archive-integrity-tester and file-listing-generator that the entry tree and CRCs match the source.
Error message → cause → fix
Exact symptoms mapped to the real cause in the converter code.
| Symptom / message | Real cause | Fix |
|---|---|---|
| 'GZIP target supports a single file only' | targetFormat: gz on a multi-entry archive | Switch targetFormat to tar.gz |
| 'appears to be encrypted' / passphrase error | Password-protected 7z/rar/zip input | Decrypt locally first; libarchive can't take passwords |
| 'libarchive WASM extraction failed' | WASM blocked or worker URL not configured | Allowlist WASM / try another browser; ZIP/GZIP/TAR still work |
| 'Could not detect or extract archive format' | File isn't a recognized archive (or is corrupt) | Confirm it's a real archive; try corrupted-zip-repair for ZIPs |
| Blocked before processing | Over tier size (50 MB Free) or entries (500 Free) | Reduce, split, or upgrade tier |
| Output missing exec bit / wrong dates | By design — mode 0644, mtime now | Re-chmod after extract; normalize timestamps |
| Symlinks became plain files | By design — ZIP/TAR rebuild has no links | Re-create links after extraction |
Tier limits that block conversion
Both caps apply per archive — size and entry count are checked separately.
| Tier | Max size | Max entries | Files per 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
Symptom-first diagnoses. Each block shows what you saw and the exact resolution.
GZIP failed on a multi-file archive
The single most common error. GZIP cannot hold more than one entry.
You did: targetFormat: gz on project.zip (12 files)
Error: GZIP target supports a single file only —
input archive must contain exactly one entry.
Fix: set targetFormat to tar.gz instead.Encrypted 7z won't convert
libarchive WASM cannot decrypt; there is no password field on this tool.
You did: dropped secret.7z (password-protected)
Error: 7z archive 'secret.7z' appears to be encrypted.
libarchive.js does not accept passwords.
Fix: decrypt with 7-Zip locally, then convert the
plaintext archive. (ZIP path supports AES only
on password-aware tools, not this converter.)7z fails but ZIP works
Classic signature of WebAssembly being blocked.
Symptom: .zip and .tar.gz convert fine,
but every .7z / .rar throws a WASM error.
Cause: a browser extension/policy is blocking WebAssembly
(libarchive runs as WASM; fflate does not).
Fix: allowlist the page or use another browser.Rejected before it even starts
An over-limit archive is blocked up front — check entries too.
File: logs.zip — 8 MB but 1,240 entries
Tier: Free (limit 500 entries)
Result: blocked — entry count over Free cap,
even though 8 MB is well under 50 MB.
Fix: upgrade to Pro (50,000 entries) or split first.Conversion 'lost' my timestamps
Not a bug — the TAR builder stamps the current time.
Observed: every entry's date = today after convert.
Reason: buildTar sets mtime = now; ZIP repack drops dates too.
Fix: run timestamp-normalizer on the output
(e.g. targetTimestamp 1980-01-01) for stable dates.Edge cases and what actually happens
GZIP target with multiple entries
RejectedGZIP is a single-stream format. Selecting gz for an archive with more than one entry throws 'GZIP target supports a single file only — input archive must contain exactly one entry.' Use tar.gz to bundle multiple files.
Password-protected input
RejectedThe converter has no password field, and libarchive WASM cannot accept passwords for 7z/rar/bz2/xz. Encrypted inputs fail with an 'appears to be encrypted' message. Decrypt locally first, then convert the plaintext archive.
WebAssembly blocked in the browser
Engine error7z/rar/bz2/xz reads depend on libarchive WASM. If an extension or enterprise policy blocks WebAssembly, those inputs throw a WASM extraction error. ZIP/GZIP/TAR/TAR.GZ (pure fflate) still convert. Allowlist or switch browser.
File over the tier size cap
Over limitFree rejects archives over 50 MB. The check is on the input file size before conversion. Pro raises it to 500 MB, Pro-media and Developer to 2 GB.
Archive over the entry-count cap
Over limitIndependent of size: Free allows 500 entries, so an 8 MB archive with 1,200 files is still blocked. Pro allows 50,000, Pro-media/Developer 500,000. Split the archive or upgrade.
Unrecognized or corrupt input
FailedIf magic-byte detection finds no known format and the ZIP fallback also fails, the tool throws 'Could not detect or extract archive format.' For a damaged ZIP specifically, try corrupted-zip-repair first.
Missing executable bit after converting to ZIP
By designOutput entries default to mode 0644 and ZIP has no standard Unix mode field, so executables come out non-executable. This is a format limit, not an error — re-chmod after extraction.
Timestamps all show today
By designThe TAR builder writes mtime as the current time, and ZIP/GZIP repacking does not carry source dates. For reproducible dates, run timestamp-normalizer on the output.
Symlinks became regular files
FlattenedZIP cannot represent symlinks/hardlinks and the rebuilt TAR writes regular-file headers, so link entries become plain files. Re-create them after extraction.
Mislabeled extension (a .zip that is really a 7z)
HandledDetection reads magic bytes, not the extension, so a misnamed file still converts from its true format. Only a genuinely unrecognized or corrupt file errors out.
Frequently asked questions
Why did GZIP conversion fail with 'single file only'?
GZIP is a single-stream format — it can hold exactly one file. If your input archive has more than one entry and you pick gz, it throws. Choose tar.gz instead, which packs many files into one compressed stream.
Why won't my password-protected archive convert?
This converter has no password field, and libarchive WASM (the engine for 7z/rar/bz2/xz) cannot accept passwords at all. Decrypt the archive locally with 7-Zip/WinRAR first, then convert the plaintext version.
Why do 7z and rar files fail when ZIP works fine?
7z/rar/bz2/xz are read through libarchive WebAssembly, while ZIP/GZIP/TAR use fflate (plain JS). If a browser extension or enterprise policy blocks WebAssembly, only the WASM-dependent inputs fail. Allowlist the page or try another browser.
Why was my file rejected before anything happened?
It exceeded a tier limit. Free caps archives at 50 MB and 500 entries. Note both caps apply — a small archive with hundreds of files can trip the entry limit. Upgrade to Pro (500 MB / 50,000) or split the archive.
Why are all my file dates wrong after converting?
Not a bug. The TAR builder stamps each entry's mtime with the current time, and ZIP/GZIP repacking drops source dates. Run timestamp-normalizer afterward to set stable timestamps.
Why did my executable scripts lose their +x bit?
Output entries default to mode 0644 and ZIP has no standard Unix mode field, so permission bits don't survive. Re-apply with chmod +x after extraction.
Why did my symlinks turn into regular files?
ZIP can't represent symlinks or hardlinks, and the rebuilt TAR writes regular-file headers, so links are flattened to plain files. Re-create them after extraction.
What does 'Could not detect or extract archive format' mean?
Magic-byte detection found no known archive format and the ZIP fallback also failed — the file isn't a supported archive or is corrupt. For a damaged ZIP, try corrupted-zip-repair.
It seems stuck on a large archive — is it frozen?
Big archives decompress and repack entirely in memory in your tab, which can take a while and spike RAM. If it's near the tier cap it may just be slow, not stuck. For very large files, use a higher tier or the CLI; close other heavy tabs to free memory.
Can I just change the file extension instead of converting?
No. Renaming .tar.gz to .zip does not change the bytes — the container format is different. You must actually convert so the data is repacked under the target format's structure.
Why can't I convert several archives at once?
The converter takes one archive per run (Free allows one file). For batch UNPACKING in the browser, use batch-extraction-manager; for scripted batch conversion, use the CLI.
How do I confirm the conversion didn't corrupt anything?
Drop the output into archive-integrity-tester to verify CRCs and file-listing-generator to confirm the entry tree matches the source.
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.