How to troubleshooting the zip metadata extractor
- Step 1Read the exact error text — The two errors you can hit are 'Not a valid ZIP archive (or unsupported format for metadata extraction).' and 'File "<name>" exceeds the <tier> tier per-job limit (<size>). Upgrade for larger files.' Match yours to one of these first.
- Step 2If 'Not a valid ZIP archive' — check the real format — Run /archive-tools/auto-format-detector. It reads the magic bytes and tells you the true format. A renamed
.7z/.rar/.tar.gzis the usual culprit — those are unsupported here because this tool parses the ZIP central directory only. - Step 3If it IS a ZIP but still fails — suspect corruption — A ZIP whose End Of Central Directory record is missing or whose directory is damaged before the first entry produces zero entries and the same error. Try /archive-tools/corrupted-zip-repair to recover what is salvageable, then re-run.
- Step 4If it's the tier-limit error — check file size — Free caps at 50 MB, Pro at 500 MB, Pro-media and Developer at 2 GB. The check runs on
file.sizebefore processing. Either upgrade or split the archive with /archive-tools/archive-splitter. - Step 5If the report is short — count vs totalEntries — Compare the entries array length against the top-level
totalEntries. If the array is shorter, the directory was truncated and parsing stopped at a bad record. IftotalEntrieslooks wrong on a huge archive, you may be over the 65,535 16-bit count limit. - Step 6If nothing happens at all — refresh and check extensions — Hard-refresh (Ctrl+Shift+R) to drop a stale cached build, then retry in a private/incognito window with extensions off to rule out a content blocker interfering with the page scripts.
Error and symptom decoder
Every failure mode, its real cause in the code, and the fix or sibling tool.
| Symptom / error | Real cause | Fix |
|---|---|---|
| 'Not a valid ZIP archive (or unsupported format for metadata extraction).' | EOCD not found — non-ZIP file, empty ZIP, or directory damaged before first entry (entries.length === 0) | Confirm format with /archive-tools/auto-format-detector; repair with /archive-tools/corrupted-zip-repair |
Same error on a .7z / .rar / .tar.gz | Tool is ZIP-only — no libarchive bridge | Use /archive-tools/archive-previewer or convert via /archive-tools/tar-gz-to-zip |
| 'File "…" exceeds the … tier per-job limit (…)' | file.size over the tier cap (checked before processing) | Upgrade tier or split with /archive-tools/archive-splitter |
| Fewer entries than expected | Truncated central directory — parser stops at first record missing signature 0x02014b50 | Repair with /archive-tools/corrupted-zip-repair |
| totalEntries looks wrong on a giant archive | 16-bit EOCD entry count wraps past 65,535 (ZIP64 not followed) | Use a ZIP64-aware tool; check entry count elsewhere |
Names show as \uFFFD (replacement char) | Non-UTF-8 filename decoded leniently; flags.utf8 is false | Expected; sanitise on extraction via /archive-tools/filename-sanitizer |
| Stuck on 'Processing…' / blank result | Stale cached build or extension interfering — NOT a server timeout | Hard-refresh (Ctrl+Shift+R); retry with extensions off |
What this tool can and cannot do
Resetting expectations prevents most 'it doesn't work' reports.
| Question | Answer |
|---|---|
| Reads 7z / RAR / TAR / XZ? | No — ZIP central directory only |
| Outputs CSV? | No — JSON only (<name>-metadata.json) |
| Has any options/settings? | No — empty schema; it just reads and reports |
| Reads comment / extra-field text? | No — only hasComment / hasExtraField booleans |
| Decrypts or needs a password? | No — reads plaintext directory; encrypted archives read fine |
| Accepts multiple files / folders? | No — single file per run |
| Has a processing timeout? | No — parsing is near-instant |
| Uploads the file? | No — read in-tab via the File API |
Cookbook
Step-by-step diagnostics for the failures users actually hit. Run these in order.
'Not a valid ZIP archive' on a file you believe is a ZIP
The error means the EOCD signature was not found in the last 65,557 bytes. The fastest triage is to confirm the real format by magic bytes — extension lies are the top cause.
Error shown: Not a valid ZIP archive (or unsupported format for metadata extraction). Step 1 — confirm the true format: /archive-tools/auto-format-detector → reports '7z' → The .zip was actually a 7-Zip archive. This tool is ZIP-only. List it with /archive-tools/archive-previewer instead.
It really is a ZIP but still errors — corruption
If auto-format-detector confirms ZIP yet extraction still throws, the central directory is likely damaged or the EOCD was truncated by an incomplete download. Repair, then re-run.
auto-format-detector → 'zip' (so it IS a ZIP) Metadata Extractor → still 'Not a valid ZIP archive…' Likely: truncated download or damaged EOCD. Step — attempt recovery: /archive-tools/corrupted-zip-repair Then re-run the Metadata Extractor on the repaired output.
Tier-limit error on a large archive
This error fires before any parsing, comparing file.size to your plan's cap. It is not corruption. Either move up a tier or split the archive into parts under the cap.
Error:
File "backup.zip" exceeds the free tier per-job limit
(50 MB). Upgrade for larger files.
Options:
• Upgrade — Pro 500 MB, Pro-media / Developer 2 GB
• Split first with /archive-tools/archive-splitter,
then run the extractor on each partReport shows fewer entries than the archive contains
Compare the entries array length to the top-level totalEntries. A shorter array means parsing stopped early at a record missing the central-directory signature — a sign of a truncated directory.
{
"archive": "big.zip",
"totalEntries": 412, <-- EOCD claims 412
"entries": [ ...only 118... ] <-- parser stopped early
}
→ Directory truncated after entry 118. Recover with
/archive-tools/corrupted-zip-repair, then re-run.Filenames come back with replacement characters
When flags.utf8 is false, the name was stored in a legacy code page. The tool decodes leniently, so undecodable bytes show as U+FFFD. This is expected behaviour, not a bug.
{
"name": "caf\uFFFD.txt",
"flags": { "encrypted": false, "utf8": false,
"dataDescriptor": false }
}
→ Original was likely 'café.txt' in CP-1252.
Not corruption. Clean names on extraction with
/archive-tools/filename-sanitizer .Edge cases and what actually happens
Non-ZIP file (7z / RAR / tar.gz / xz)
Unsupported formatThe tool parses the ZIP central directory only and has no libarchive path, so any non-ZIP throws 'Not a valid ZIP archive (or unsupported format for metadata extraction).' Identify the real format with /archive-tools/auto-format-detector and list non-ZIP archives with /archive-tools/archive-previewer.
Empty ZIP (valid file, zero entries)
RejectedAn archive with a valid EOCD but no entries produces an empty entries array, and the entries.length === 0 guard throws the same 'Not a valid ZIP archive…' message. The check cannot tell an empty ZIP from a non-ZIP — both have nothing to report.
File over the tier cap
Tier limit exceededBefore parsing, the client checks file.size and throws 'File "<name>" exceeds the <tier> tier per-job limit (<size>). Upgrade for larger files.' Free 50 MB, Pro 500 MB, Pro-media / Developer 2 GB. Split with /archive-tools/archive-splitter or upgrade.
Truncated central directory
Partial reportParsing advances entry-by-entry and stops at the first record that does not begin with the central-directory signature 0x02014b50. You get a partial report whose entries length is below totalEntries. Recover with /archive-tools/corrupted-zip-repair.
More than 65,535 entries (ZIP64)
Count overflowThe entry count comes from the 16-bit EOCD field, which wraps past 65,535; the loop may stop early because true ZIP64 directory locators are not followed. The free/pro entry caps (500 / 50,000) keep typical inputs well within range; for genuinely huge ZIP64 archives, verify the count with a ZIP64-aware tool.
Encrypted ZIP with no password supplied
SupportedMetadata extraction needs no password — the central directory is plaintext. You will see flags.encrypted: true and (for AES) compressionMethod: 'AES' with a zero CRC. To test a candidate password use /archive-tools/archive-password-tester; this tool never reads payloads.
Stuck on 'Processing…' or a blank result
UI / cache issueThere is no server timeout — central-directory parsing is near-instant. A hang almost always means a stale cached build or a browser extension interfering with page scripts. Hard-refresh (Ctrl+Shift+R), then retry in a private window with extensions disabled.
Very large ZIP exhausts device memory
Memory limitThe whole file is read into an ArrayBuffer (file.arrayBuffer()) before parsing, so a multi-GB archive on a low-memory device can fail to allocate. Stay within your tier's size cap and use a desktop browser for the largest archives.
Self-extracting archive (.exe + appended ZIP)
SupportedThe EOCD is found by scanning backward from the end of the file, so an executable stub in front of the ZIP does not break parsing — the stub bytes are ignored and entries read normally.
Frequently asked questions
Why do I get 'Not a valid ZIP archive (or unsupported format for metadata extraction)'?
The tool could not find the ZIP End Of Central Directory record, so it parsed zero entries. Three causes: the file is not a ZIP (often a renamed 7z/RAR/tar.gz), the ZIP is genuinely empty, or its directory is damaged before the first entry. Confirm the format with /archive-tools/auto-format-detector, and if it really is ZIP, try /archive-tools/corrupted-zip-repair.
Why won't it read my .7z / .rar / .tar.gz?
By design — this tool parses the ZIP central directory only and does not use the libarchive WASM bridge, so non-ZIP formats are unsupported. List them with /archive-tools/archive-previewer, or convert a tar.gz to ZIP with /archive-tools/tar-gz-to-zip and then re-run.
Is there a 30-second processing timeout?
No. Central-directory parsing is near-instant even for thousands of entries, and there is no server round-trip, so there is no timeout. If you appear stuck on 'Processing…', the cause is a stale cached build or an extension — hard-refresh and retry with extensions off.
What does the tier-limit error mean exactly?
'File "<name>" exceeds the <tier> tier per-job limit (<size>). Upgrade for larger files.' It is thrown before processing, comparing file.size to your plan's cap (Free 50 MB, Pro 500 MB, Pro-media / Developer 2 GB). It is not corruption — upgrade or split with /archive-tools/archive-splitter.
Why does my report have fewer entries than the archive?
Compare the entries array length to the top-level totalEntries. A shorter array means parsing stopped at a record missing the 0x02014b50 signature — a truncated or damaged directory. Recover with /archive-tools/corrupted-zip-repair. On a giant archive, a wrong totalEntries can mean the 16-bit count overflowed past 65,535.
Why are some filenames showing odd characters?
Those entries have flags.utf8: false — the name was stored in a legacy code page (e.g. CP-1252). The tool decodes names leniently, replacing undecodable bytes with U+FFFD. This is expected. To normalise names on extraction, use /archive-tools/filename-sanitizer.
Do I need the password to read an encrypted ZIP's metadata?
No. The central directory is plaintext, so names, sizes, methods, timestamps, and flags.encrypted all read without a password. Only payloads are encrypted, and this tool never reads payloads. To test a password, use /archive-tools/archive-password-tester.
Can it output CSV instead of JSON?
No — JSON only, downloaded as <name>-metadata.json. If you need CSV/TXT, use /archive-tools/file-listing-generator, which offers csv/json/txt output of names, sizes, ratios, methods, CRCs and the encryption flag.
Are my files uploaded when something fails?
Never. Archive tools are browser-only (browserOnly: true) — the file is read in-tab via the File API. Errors are thrown locally during parsing; no bytes leave the machine even on failure.
The tool has no options panel — is that a bug?
No. The Metadata Extractor has an empty options schema by design — it just reads the directory and emits the report. There is nothing to configure. Tools like the splitter or checksum generator have options because their behaviour varies; this one does not.
Why is an AES entry's CRC all zeros?
AES-encrypted entries (compressionMethod: 'AES', flags.encrypted: true) commonly store crc32: '00000000' because the real CRC is protected with the encrypted data. That is expected — only a zero CRC on a plaintext entry is a concern.
What if the file is huge and my browser crashes?
The whole archive is read into memory as an ArrayBuffer before parsing, so a multi-GB file on a low-memory device can fail to allocate. Use a desktop browser, stay within your tier's size cap (2 GB max on paid tiers), and split oversized archives with /archive-tools/archive-splitter.
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.