nodejs/node · error · Exception

Error: Don't know how to unpack %s with extension %s

Error message

Error: Don't know how to unpack %s with extension %s

What it means

Raised by unpacking logic in Node's tools/configure.d/nodedownload.py when the downloaded file is neither a valid zip (zipfile.is_zipfile false) nor a valid tar (tarfile.is_tarfile false). The script can only extract these two archive formats for auto-downloaded artifacts like ICU.

Source

Thrown at tools/configure.d/nodedownload.py:80

        digest.update(chunk)
        chunk = f.read(1024)
    return digest.hexdigest()

def unpack(packedfile, parent_path):
    """Unpacks packedfile into parent_path. Assumes .zip. Returns parent_path"""
    if zipfile.is_zipfile(packedfile):
        with contextlib.closing(zipfile.ZipFile(packedfile, 'r')) as icuzip:
            print(' Extracting zipfile: %s' % packedfile)
            icuzip.extractall(parent_path)
            return parent_path
    elif tarfile.is_tarfile(packedfile):
        with contextlib.closing(tarfile.TarFile.open(packedfile, 'r')) as icuzip:
            print(' Extracting tarfile: %s' % packedfile)
            icuzip.extractall(parent_path)
            return parent_path
    else:
        packedsuffix = packedfile.lower().split('.')[-1]  # .zip, .tgz etc
        raise Exception('Error: Don\'t know how to unpack %s with extension %s' % (packedfile, packedsuffix))

# List of possible "--download=" types.
download_types = set(['icu'])

# Default options for --download.
download_default = "none"

def help():
  """This function calculates the '--help' text for '--download'."""
  return """Select which packages may be auto-downloaded.
valid values are: none, all, %s. (default is "%s").""" % (", ".join(download_types), download_default)

def set2dict(keys, value=None):
  """Convert some keys (iterable) to a dict."""
  return dict((key, value) for (key) in keys)

def parse(opt):
  """This function parses the options to --download and returns a set such as { icu: true }, etc. """

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Delete the cached download and re-run configure --download to fetch a fresh, complete archive.
2. Verify the file with `file <downloaded>` and inspect its first bytes — an HTML page indicates a proxy/mirror error.
3. If the format genuinely changed, add the new format's extraction branch to nodedownload.py (matching zip/tar pattern) or convert the artifact to a supported format upstream.

Example fix

# before
./configure --download=icu   # corrupt cached file
# after
rm -rf ~/.cache/.../icu-src.tgz   # or the configured download cache
./configure --download=icu

import zipfile, tarfile
def is_supported_archive(path: str) -> bool:
    return zipfile.is_zipfile(path) or tarfile.is_tarfile(path)

null

try:
    unpack(downloaded)
except Exception as e:
    if "Don't know how to unpack" in str(e):
        print('Archive corrupt or unsupported; delete cache and re-download.')
    raise

When it happens

Trigger: configure's --download path fetches a file (e.g. ICU source) and passes it to the unpack routine, but the file is corrupt, truncated, or in an unsupported format (not .zip/.tgz/.tar.gz), so both format probes fail.

Common situations: A partially downloaded/corrupt archive (network drop, proxy truncation); a checksum-mismatched re-served HTML error page saved with a .tgz extension; an upstream artifact format change to an unsupported type.

Related errors

• Internal error: "%s" is not in the --downloads list. Check n
• Error creating data archive library file.
• --enable-v8windbg is incompatible with --without-bundled-v8.
• --v8-enable-hugepage is supported only on linux.
• Only one of the --v8-enable-object-print or --v8-disable-obj

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/140a65b86d60e78c. Report an issue: GitHub.