How to troubleshooting the streaming zip builder
- Step 1Confirm your tier — The Builder is
minTier: "pro". On Free, Generate is gated behind an upgrade prompt — this is the single most common 'it won't run' cause. Upgrade to Pro or higher, or use a local fflate/CLI script instead. - Step 2Check the per-file size cap — Each dropped file is checked against your tier cap: 500 MB (Pro), 2 GB (Pro+Media / Developer). An oversized file throws an error naming the file and the cap before any packing. Split the file or upgrade.
- Step 3Check the entry count — The per-archive entry limit is 50,000 (Pro) or 500,000 (Pro+Media / Developer). Packing huge numbers of tiny files can exceed it before the size cap. Bundle fewer files or move to a higher tier.
- Step 4Rule out memory pressure for big jobs — The finished ZIP is assembled as one in-memory Blob. If a near-cap job makes the tab sluggish or crash, you're memory-bound, not timed-out. Close other tabs, or use a disk-streaming CLI for the largest jobs.
- Step 5Drop at least one file — Generating with an empty dropzone throws 'Drop one or more files to stream-pack.' Make sure files actually landed in the Drop files to process zone before clicking Generate.
- Step 6Reconcile expectations with what the tool offers — No password, no level slider, no format dropdown, no output-name field — it's a fixed level-6 ZIP named streaming.zip. If you need any of those, the fix is to use the right sibling tool, not to look harder for an option.
Error / symptom -> cause -> fix
Symptoms grounded in archive-tool-client.tsx and archive-processor.ts. Wording may vary slightly by build.
| Symptom | Cause | Fix |
|---|---|---|
| Generate is disabled / upgrade prompt | Tool is Pro-tier; you're on Free | Upgrade to Pro+, or use local fflate/CLI |
| 'exceeds the <tier> tier per-job limit' | A dropped file is over the size cap | Split the file or upgrade tier |
| Entry-limit error | Too many entries for the tier | Pack fewer files per archive or upgrade |
| 'Drop one or more files to stream-pack.' | No files in the dropzone | Add at least one file, then Generate |
| Tab sluggish / crashes on a big job | Finished ZIP held in browser memory | Close tabs; or use a disk-streaming CLI |
| Output ~0% smaller than input | Inputs already compressed (JPEG/MP4/zip) | Expected — bundling, not shrinking |
| Folder tree flattened | No relative paths supplied by browser | Use folder-to-zip |
Myth vs reality
Corrections to claims that don't match the real streaming-zip-builder implementation.
| Claim you may have seen | Reality |
|---|---|
| It's free up to 50 MB | It's Pro-tier and up; Free can't run it (the 50 MB cap is the Free archive limit, but the tool is gated) |
| Processing throws a 30-second timeout | There's no such timeout in the code; long jobs are memory/CPU bound, not time-capped |
| WASM init can stall it | This tool uses pure-JS fflate — no WASM module loads, so there's no WASM-init step to stall |
| You can set a compression level | Fixed DEFLATE level 6; no level control exists |
| It can password-protect the ZIP | No encryption; use encrypted-zip-creator |
Cookbook
Step-by-step diagnostics for the symptoms users actually report.
Diagnose 'it won't run' on Free
The most common report. The Builder is Pro-gated, so on Free the Generate action never processes.
Symptom: clicking Generate shows an upgrade prompt, no ZIP. Check: account tier. Free -> tool gated (expected) Pro+ -> runs Fix: upgrade, or build the ZIP locally with fflate/CLI.
Diagnose a rejected oversized file
A single file over the cap is rejected before packing, with a message naming the file and limit.
Error: File "db-dump.sql" exceeds the pro tier per-job limit (500 MB). Upgrade for larger files. Fix: - split db-dump.sql, or - upgrade to Pro+Media/Developer (2 GB cap)
Diagnose stuck on Processing…
There is no timeout; a long-running job is doing real work or running out of memory. Distinguish the two.
If Processing… persists on a LARGE job: -> likely memory-bound (finished ZIP held as one Blob) -> close tabs / reduce job size / use a CLI If Processing… persists on a SMALL job: -> hard-refresh (Ctrl+Shift+R) to drop a stale cached chunk
Diagnose unexpected output size
Compression varies by content; near-zero on already-compressed inputs is correct, not a bug.
Input: 3 x .mp4 (already compressed) Output: ~same size, compression ~0.1% -> EXPECTED Input: 100 x .log (text) Output: ~18% of original, compression ~82% -> EXPECTED For a per-file breakdown use /archive-tools/compression-ratio-calculator
Diagnose a flattened folder tree
Entry paths only carry folders when the browser supplies relative paths. If your ZIP is flat, switch tools.
Cause: files selected individually -> entries named by file name only (no folders). Fix: drag the folder in Chromium (populates webkitRelativePath), OR use /archive-tools/folder-to-zip for a guaranteed directory tree.
Edge cases and what actually happens
Generate does nothing on the Free tier
Upgrade requiredThe Streaming ZIP Builder is minTier: "pro"; the Generate action is gated on Free. This is the leading 'not working' report. Upgrade, or build the same DEFLATE ZIP locally with fflate or a CLI at no cost.
Single file over the per-job size cap
RejectedFiles are checked against the tier cap before packing (500 MB Pro; 2 GB Pro+Media / Developer). The error names the file and the limit and nothing is packed. Split the file or upgrade.
Entry count over the archive limit
Limit exceededThe per-archive entry limit (50,000 Pro; 500,000 Pro+Media / Developer) can be hit by many small files before the size cap. Bundle into fewer archives or upgrade.
Empty dropzone
RejectedGenerating with no files throws 'Drop one or more files to stream-pack.' Confirm files actually landed in the dropzone (the list shows their names) before clicking Generate.
Stuck on Processing… (large job)
Memory-boundThere is no processing timeout in the code. On a large job the tab can stall because the finished ZIP is assembled as one in-memory Blob. Reduce the job, close other tabs, or use a disk-streaming CLI — it is not a time-cap error.
Stuck on Processing… (small job)
Stale cacheIf a small job hangs, you may be on an old cached build of the page chunk. Hard-refresh (Ctrl+Shift+R) to fetch the latest. This is environmental, not a tool fault.
Output isn't smaller than the input
ExpectedAlready-compressed inputs (JPEG, PNG, MP4, MP3, existing ZIPs) can't be shrunk by DEFLATE level 6; the compression percent near zero is correct. Use compression-ratio-calculator for a per-file view.
Looking for a password or level option that isn't there
Not supportedThe tool has zero options. If you need encryption use encrypted-zip-creator; for a tunable level use smart-archive-compressor; for a non-ZIP format use the converters. Don't keep hunting for a control that doesn't exist.
Expected a 30-second timeout error
MythOlder docs mentioned a 30-second timeout and a WASM-init stall for this tool. Neither exists in the real implementation — it's a pure-JS fflate path with no time cap and no WASM module. Treat long runs as memory/CPU bound.
Duplicate entry paths in the output
CautionTwo dropped files that resolve to the same entry path produce duplicate entries; unzippers handle that inconsistently. Ensure files have distinct names or distinct relative paths before packing.
Frequently asked questions
Why won't the tool run for me?
Most likely you're on the Free tier — the Streaming ZIP Builder requires Pro or higher (minTier: "pro"), so Generate is gated. Upgrade, or build the same DEFLATE ZIP locally with fflate or a command-line archiver.
Why does it say my file is too big?
A single dropped file exceeded your tier's per-job cap: 500 MB on Pro, 2 GB on Pro+Media and Developer. The error names the file and the limit, and nothing is packed. Split the file or upgrade for a larger cap.
Why does it stay on 'Processing…'?
There's no timeout — long runs are doing real work or running out of memory because the finished ZIP is assembled in one in-memory Blob. On big jobs, reduce the job or close tabs. On small jobs that hang, hard-refresh (Ctrl+Shift+R) to drop a stale cached build.
Is there really no 30-second timeout?
Correct. Older docs claimed a 30-second processing timeout and a WASM-init stall; neither is in the real implementation. This tool runs on pure-JavaScript fflate with no time cap and no WASM module to initialise.
Why is my ZIP barely smaller than the input?
Because the inputs are already compressed. JPEG, PNG, MP4, MP3, and existing ZIPs are entropy-dense, so DEFLATE level 6 can't shrink them — a compression percent near zero is expected. Text and source code compress far better. The compression-ratio-calculator breaks it down per file.
Why is my folder structure gone in the ZIP?
Entry paths only include folders when the browser populates webkitRelativePath — which happens when you drag a folder in a Chromium browser. Selecting loose files gives flat entries. For a guaranteed directory tree, use folder-to-zip.
Where's the compression-level or password option?
There isn't one — the tool has no options at all. It's a fixed DEFLATE level 6, plaintext ZIP. For a level slider use smart-archive-compressor; for AES-256 use encrypted-zip-creator.
Why can't I rename the output before downloading?
The output filename is hard-coded to streaming.zip — there's no name field. Rename the downloaded file in your OS; the archive contents and CRCs are unchanged.
Why did entries get duplicated?
If two dropped files resolve to the same entry path (same name, no distinguishing relative path), they both go into the ZIP as duplicate entries, and unzippers handle that inconsistently. Give files distinct names or distinct relative paths before packing.
Does any of my data leave my machine while troubleshooting?
No. Even on error, files are read and packed locally by fflate — nothing is uploaded. You can confirm with DevTools -> Network: no request carries your file bytes (only the one-time fflate library chunk loads).
What browser issues actually affect this tool?
Few, because it's pure JavaScript. The relevant ones are: low available memory on large jobs, and a stale cached page chunk (fixed by a hard refresh). Folder drag-drop with relative paths is most reliable in Chromium browsers. There's no WASM or extension-channel dependency to break.
When should I just use a different tool?
Use encrypted-zip-creator for a password, smart-archive-compressor for a chosen level, folder-to-zip for a guaranteed tree, or the converters for tar.gz. If you need scriptable/multi-GB-to-disk output, a CLI is the better fit.
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.