How to troubleshooting the format detector
- Step 1Confirm a file is actually loaded — If nothing happens, make sure you dropped a single file onto the upload zone. With no file, the tool reports 'Drop an archive file to process.' rather than detecting anything.
- Step 2Check the file against your tier's size cap — If you get a rejection naming the limit, the file exceeds your cap — 50 MB on Free, 500 MB on Pro, 2 GB on Developer. Compress, trim, or upgrade. Detection needs only the header, but the size check applies to the whole file.
- Step 3Read the Format and Magic-bytes metrics — Look at both result fields. If Format is
unknown, the magic hex tells you what the file actually starts with — for example4D 5A(MZ) means an EXE, and printable ASCII means a plain text/JSON file. - Step 4Account for wrapped formats — If you expected
tar.gzbut gotgz, that's correct — the outer layer is GZIP. If you expectedtarbut gotgz, the file is compressed. Adjust your next step (decompress first) accordingly. - Step 5Rule out unsupported formats — If the file is a Zstandard, LZ4, CAB, or ISO file,
unknownis expected — those aren't in the signature set. Use a CLI likefileto identify them, or convert upstream to a supported format. - Step 6Route to the right tool for the real task — If you actually need to open, list, or convert — not just identify — use the recommended sibling. The detector never extracts or converts; it only names the container.
Symptom to cause to fix
The complete set of real failure modes. Detection is deterministic and local, so there are no network or timeout errors.
| Symptom | Cause | Fix |
|---|---|---|
| 'Drop an archive file to process.' | No file loaded | Drop a single file onto the upload zone |
| Rejected, message names a size in MB/GB | File over the tier cap | Compress/trim the file or upgrade tier |
Result is unknown | Unsupported format / non-archive / ISO / EXE | Read the hex; use file for exotic formats |
.tar.gz shows gz | Detector reports the outer layer | Expected — unwrap with tar-gz-to-zip |
.tgz shows tar | File isn't actually gzipped | Open as a plain TAR; don't gunzip |
Real archive but unknown | Truncated / sub-4-byte / TAR under 262 B | Re-download; ensure the file is complete |
Decoding an unknown result from the hex
When Format is unknown, the first bytes of magic hex usually reveal what the file really is.
| Leading hex | Likely file | What to do |
|---|---|---|
| 4D 5A | Windows EXE (MZ) / self-extracting archive | Treat as executable; don't extract here |
| 25 50 44 46 | Real PDF (%PDF) | Open in a PDF viewer, not an archive tool |
| 7B / 5B | JSON ({ or [) | It's text — the compression step never ran |
| 28 B5 2F FD | Zstandard | Unsupported here; use file / zstd CLI |
| printable ASCII | Plain text / log / CSV | Not an archive; check the source |
| 00 00 ... | Empty / zero-filled / truncated | Re-download the file |
What the detector cannot do
If your goal isn't identification, the detector isn't the tool — use the sibling.
| Expectation | Reality | Correct tool |
|---|---|---|
| Extract the files | Identifier only | multi-format-extractor |
| List entries | Container only | archive-previewer |
| Convert format | No conversion | tar-gz-to-zip / gzip-to-zip |
| Check it opens cleanly | No integrity check | archive-integrity-tester |
| Detect a password | Header format only | encrypted-archive-detector |
| Identify many files | One per run | file in a shell loop |
Cookbook
Worked diagnoses: a symptom, the result the detector gives, and how to read it to the fix.
It says unknown but I know it's a gzip
A data.gz reports unknown. The hex starts with printable ASCII, not 1F 8B — so it isn't really GZIP. The producing step wrote uncompressed data with a .gz name. The detector is right; the file is wrong.
Input: data.gz Result: Format: unknown Magic bytes: 69 64 2C 6E 61 6D 65 0A 69 64 = 'id' — this is a CSV header, not GZIP (1F 8B). Fix: re-export with compression, or treat it as plain text.
Large file rejected before it detects
An 800 MB backup.7z on the free tier is rejected with a message naming the 50 MB limit. The size check runs before detection. Upgrade to Pro (500 MB) — or, since even Pro caps at 500 MB here, identify it with a local file call.
Input: backup.7z (800 MB), tier: free Error: File "backup.7z" exceeds the free tier per-job limit (50 MB). Upgrade for larger files. Fix: Pro raises it to 500 MB; for 800 MB use a local CLI.
Expected tar.gz, got gz
A release.tar.gz reports gz and you think detection failed. It didn't — the outer bytes are GZIP, so gz is the correct true format. The inner TAR is only visible after decompression.
Input: release.tar.gz Result: Format: gz Magic bytes: 1F 8B 08 00 ... This is correct. To unwrap both layers, use tar-gz-to-zip.
Tiny TAR reports unknown
A 200-byte test TAR fixture reports unknown. TAR is matched by ustar at offset 257, so the file must be at least 262 bytes. Your fixture is too small to confirm — real TARs are far larger.
Input: tiny.tar (200 bytes) Result: Format: unknown Reason: ustar magic lives at offset 257; need >= 262 bytes. Fix: use a complete TAR, or accept that micro-fixtures won't detect.
A spoofed extension exposed
document.zip won't open and reports unknown. The hex is 4D 5A — it's a Windows executable wearing a .zip name, not an archive at all. The detector turned a confusing failure into a clear (and important) finding.
Input: document.zip Result: Format: unknown Magic bytes: 4D 5A 90 00 03 00 00 00 4D 5A = 'MZ' = Windows EXE. This is not a ZIP. Do not run it; investigate where it came from.
Edge cases and what actually happens
File exceeds the tier size cap
Rejected (tier limit)A file larger than your cap (Free 50 MB, Pro 500 MB, Developer 2 GB) is rejected before detection with a message naming the limit. Compress or trim the file, upgrade your tier, or identify it with a local CLI.
No file dropped
ErrorRunning with no file loaded reports 'Drop an archive file to process.' This isn't a malfunction — drop a single file onto the upload zone and run again.
Result is unknown for a real archive
unknownIf a genuine archive reports unknown, it's likely truncated, under 4 bytes, a TAR under 262 bytes, or a format outside the supported set. Re-download to rule out truncation and read the hex to see what the bytes actually are.
tar.gz reports gz, not tar.gz
By designThe detector reports the outermost format, which for a gzipped TAR is GZIP. It never returns tar.gz. This is correct behaviour; unwrap with the tar-gz-to-zip converter.
Unsupported format (Zstd, LZ4, CAB)
unknownThese valid archive formats have no signature in the detector's table, so they report unknown. There's no fix within this tool — use the file command or the format's own CLI to identify them.
ISO image reports unknown
unknownISO 9660's identifying descriptor sits far inside the file, beyond the header bytes inspected, so ISOs report unknown. This is a scope limit, not an error. Identify disc images with a CLI tool.
Tool appears stuck on a huge file
LoadingThere's no server timeout, but reading a near-cap file (hundreds of MB) into the browser takes a moment before detection. If it never finishes, the browser likely ran low on memory — try a smaller file or a desktop browser.
WASM blocked by a browser extension
Browser issueFormat detection itself is plain byte-reading and doesn't need WASM, so it works even where WASM is blocked. If a follow-up tool like the multi-format extractor fails to load, an extension may be blocking WebAssembly — disable it or use a clean profile.
Self-extracting EXE or polyglot reports unknown
unknownFiles starting with an executable stub (MZ) or another type at offset 0 report unknown because the leading bytes aren't an archive signature. The appended archive payload is beyond the header and isn't detected.
Frequently asked questions
Why does the detector say unknown?
Because the file's bytes match none of the supported signatures (ZIP, GZIP, TAR, BZIP2, XZ, 7z, RAR). It may be an unsupported format, an ISO, an EXE, a non-archive, or a truncated file. Read the magic hex to see what it really is.
My .gz is reported as unknown — is the tool broken?
No. A real GZIP starts with 1F 8B. If those bytes are missing, the file isn't actually GZIP regardless of its name — it was renamed, never compressed, or corrupted.
Why does my .tar.gz show gz instead of tar.gz?
The outermost bytes are GZIP, so gz is the true format. The detector reports the outer layer and never returns tar.gz. Use the tar-gz-to-zip converter to unwrap both layers.
Why was my file rejected before it even detected?
It exceeded your tier's size cap — 50 MB on Free, 500 MB on Pro, 2 GB on Developer. The size check runs before detection. Compress the file, upgrade, or use a local CLI for very large files.
Is there a timeout or server error to worry about?
No — detection runs locally in the browser with no server, so there's nothing to time out. A delay on a near-cap file is just the browser reading it into memory.
It's stuck processing — what now?
Large files take a moment to load before detection. If it truly never completes, the browser likely ran out of memory; try a smaller file, close other tabs, or use a desktop browser.
Why does my .tgz show tar?
Because it wasn't actually gzipped — it's a bare TAR with a .tgz name. Don't gunzip it; open it as a plain TAR with the multi-format-extractor.
A small TAR reports unknown — why?
TAR is matched by ustar at byte offset 257, so the file must be at least 262 bytes. Tiny test TARs fall below that threshold and can't be confirmed.
Can I detect a Zstandard or ISO file?
No — those aren't in the supported signature set and report unknown. Use the file command or the format's own CLI to identify them.
The detector won't open the archive — how do I extract it?
It only identifies the format; it never extracts. Once you know the format, use the multi-format-extractor to open it or the archive-previewer to list entries.
Does a browser extension blocking WASM break detection?
No — basic format detection is plain byte-reading and doesn't use WASM. A WASM block would only affect heavier siblings like the multi-format extractor.
The result looks wrong — how do I verify it?
Compare the reported magic-byte hex against the file's real bytes using xxd or file --hex on the CLI. Detection is deterministic, so a true mismatch usually means the file differs from what you assumed.
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.