Fix ZIP Extraction Errors — Corrupted Archives, Passwords, and Security

ZIP extraction fails with an unhelpful error. The archive might be corrupted, password-protected, use an unsupported compression method, or contain filenames with special characters. Here's how to debug every case.

Common Error Messages

• End-of-central-directory signature not found → Corrupted or truncated
• The archive is either in unknown format or damaged → Wrong format or corruption
• Unsupported compression method → Uses newer compression (LZMA, Bzip2)
• Bad password / Wrong password → Password-protected ZIP
• Filename not valid or too long → Unicode filename encoding issue
• Cannot create a file when that file already exists → Path conflict
• error: Zip Slip vulnerability detected → Path traversal attack

Fix 1: Corrupted Archive

The ZIP's central directory (at the end of file) is damaged or missing.

Diagnose:

# Test archive integrity
unzip -t archive.zip
# "At least one error was detected in archive.zip"

# Check file type — is it actually a ZIP?
file archive.zip
# Should say: "Zip archive data"
# NOT: "HTML document", "ASCII text", etc.

# Check first bytes
xxd archive.zip | head -1
# ZIP starts with: 504b 0304 ("PK..")

Common causes: Incomplete download, disk error, the file isn't actually a ZIP (might be an error page saved as .zip).

Fix: Re-download the file. If the source is reliable, use wget -c (resume) or verify checksum.

Test with corrupted ZIP files to verify your error handling.

Fix 2: Password-Protected ZIP

unzip -P "test123" protected.zip

// Node.js with adm-zip
const AdmZip = require('adm-zip');
const zip = new AdmZip('protected.zip');
zip.extractAllTo('./output', true, false, 'test123');

Our password-protected ZIP uses password test123 — use it to test your decryption handling.

Fix 3: Zip Slip Security Vulnerability

Critical security issue: A malicious ZIP contains entries with paths like ../../../etc/passwd, extracting files outside the target directory.

Vulnerable code:

// DANGEROUS — no path validation
const zip = new AdmZip('upload.zip');
zip.extractAllTo('/tmp/extracted/');  // Entry "../../../etc/cron" escapes!

Fixed code:

const zip = new AdmZip('upload.zip');
const targetDir = path.resolve('/tmp/extracted/');

for (const entry of zip.getEntries()) {
  const destPath = path.resolve(targetDir, entry.entryName);

  // SECURITY CHECK: ensure path stays within target
  if (!destPath.startsWith(targetDir + path.sep)) {
    throw new Error(`Zip Slip: ${entry.entryName} escapes target directory`);
  }

  if (entry.isDirectory) {
    fs.mkdirSync(destPath, { recursive: true });
  } else {
    fs.mkdirSync(path.dirname(destPath), { recursive: true });
    fs.writeFileSync(destPath, entry.getData());
  }
}

Fix 4: Filename Encoding (Unicode)

ZIP files from Windows may use CP437 or Shift-JIS for filenames. When extracted on Linux/Mac, you get garbled filenames.

# Extract with explicit encoding
unzip -O CP437 japanese-files.zip
# Or
7z x -scsUTF-8 archive.zip

# Python
import zipfile
with zipfile.ZipFile('archive.zip') as zf:
    for info in zf.infolist():
        # Try UTF-8 first, fall back to CP437
        try:
            name = info.filename.encode('cp437').decode('utf-8')
        except (UnicodeDecodeError, UnicodeEncodeError):
            name = info.filename
        print(name)

Fix 5: Unsupported Compression Method

Modern ZIPs may use LZMA, Bzip2, or Zstandard compression instead of DEFLATE. Older tools don't support these.

# Check compression method
7z l archive.zip
# Method column shows: Store, Deflate, LZMA, BZip2, etc.

Fix: Use 7-Zip or a modern library. Python's zipfile supports only Store and Deflate by default.

Test Matrix

| Test | File | Expected | |------|------|----------| | Valid ZIP | sample-1mb.zip | Extracts successfully | | Password ZIP | sample-with-password.zip | Prompts for password (test123) | | Nested ZIP | sample-nested.zip | ZIP inside ZIP | | Many files | sample-many-files.zip | 1000 files extract | | Corrupted | sample-corrupt.zip | Graceful error | | Large archive | sample-100mb.zip | Memory handling |

Quick Reference

| Error | Cause | Fix | |-------|-------|-----| | End-of-central-directory not found | Truncated/corrupt | Re-download, check source | | Bad password | Wrong password | Get correct password | | Unsupported compression | LZMA/Bzip2/Zstd | Use 7-Zip or update library | | Filename not valid | Unicode encoding | Specify CP437 or Shift-JIS | | Path traversal detected | Zip Slip attack | Validate extracted paths | | No space left on device | Archive contents larger than expected | Check uncompressed size first |

See also: Archive Formats Cheat Sheet · TAR.GZ files · 7Z files