{"record":{"id":"cfc4c1d4fb892a58","repo":"headroomlabs-ai/headroom","slug":"failed-to-extract-archive-name-e","errorCode":null,"errorMessage":"failed to extract {archive.name}: {e}","messagePattern":"failed to extract (.+?): (.+?)","errorType":"exception","errorClass":"BinaryFetchError","httpStatus":null,"severity":"error","filePath":"headroom/binaries.py","lineNumber":350,"sourceCode":"    name = archive.name.lower()\n    try:\n        if name.endswith(\".tar.gz\") or name.endswith(\".tgz\"):\n            with tarfile.open(archive, \"r:gz\") as tf:\n                _extract_member_from_tar(tf, member, dest)\n        elif name.endswith(\".zip\"):\n            with zipfile.ZipFile(archive) as zf:\n                _extract_member_from_zip(zf, member, dest)\n        elif name.endswith(\".gz\") and not (name.endswith(\".tar.gz\") or name.endswith(\".tgz\")):\n            # bare .gz of a single binary (e.g. `scc-linux-x86_64.gz`)\n            import gzip\n\n            with gzip.open(archive, \"rb\") as gz, dest.open(\"wb\") as out:\n                shutil.copyfileobj(gz, out)\n        else:\n            # Not an archive — treat the downloaded file itself as the binary.\n            shutil.copy2(archive, dest)\n    except (tarfile.TarError, zipfile.BadZipFile, OSError) as e:\n        raise BinaryFetchError(f\"failed to extract {archive.name}: {e}\") from e\n\n\ndef _extract_member_from_tar(tf: tarfile.TarFile, member: str, dest: Path) -> None:\n    # Match by basename so that registries can specify \"difft\" even though the\n    # upstream tar may include a leading directory like \"difft-0.64.0/difft\".\n    wanted = member.lower()\n    for m in tf.getmembers():\n        base = m.name.rsplit(\"/\", 1)[-1].lower()\n        if base == wanted and m.isfile():\n            extracted = tf.extractfile(m)\n            if extracted is None:\n                continue\n            with dest.open(\"wb\") as out:\n                shutil.copyfileobj(extracted, out)\n            return\n    raise BinaryFetchError(f\"archive did not contain expected member {member!r}\")\n\n","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/binaries.py#L332-L368","documentation":"_extract wraps all unpacking (tarfile, zipfile, gzip, plain copy) and converts tarfile.TarError, zipfile.BadZipFile, and OSError into BinaryFetchError chained with 'from e'. It means the artifact was fetched and its sha256 (if pinned) verified, but the bytes still could not be unpacked — truncated archive, corrupt compressed stream, or an I/O failure mid-copy.","triggerScenarios":"A gzip/tar/zip archive that is structurally invalid despite passing an (absent) sha256 pin: 'not a gzip file', 'unexpected end of data', EOF truncation, or disk-full (ENOSPC) while writing the extracted binary.","commonSituations":"Unpinned upstream artifacts that were later corrupted, a mirror serving error pages (HTML) for asset URLs, partial writes from an interrupted earlier download, or a full disk / quota on the cache volume.","solutions":["Identify the artifact: file <archive> — 'HTML document' means the mirror/proxy served an error page; fix the mirror or bypass it.","Clear the corrupted cache entry and re-download from a clean source (the mismatching artifact was cached before extraction failed only if sha was unpinned).","Check disk space on the cache volume: df -h <cache-dir>; ENOSPC surfaces as OSError here.","Prefer sha256-pinned registry entries so corrupt downloads are caught before extraction is attempted."],"exampleFix":"# before\n# BinaryFetchError: failed to extract scc-linux-x86_64.gz: Not a gzipped file\n\n# after: the 'archive' was a proxy error page; bypass the mirror\nHEADROOM_BINARIES_MIRROR= headroom doctor","handlingStrategy":"try-catch","validationCode":"import gzip, tarfile, zipfile\n\ndef archive_intact(path: str) -> bool:\n    name = path.lower()\n    try:\n        if name.endswith((\".tar.gz\", \".tgz\")):\n            tarfile.open(path).getmembers()\n        elif name.endswith(\".zip\"):\n            zipfile.ZipFile(path).testzip()\n        elif name.endswith(\".gz\"):\n            with gzip.open(path, \"rb\") as f:\n                f.read()\n        return True\n    except (tarfile.TarError, zipfile.BadZipFile, OSError):\n        return False","typeGuard":null,"tryCatchPattern":"from headroom.binaries import BinaryFetchError\n\ntry:\n    ensure_binary(tool)\nexcept BinaryFetchError as e:\n    if \"failed to extract\" in str(e):\n        purge_cache_entry(tool)          # drop the corrupt artifact\n        ensure_binary(tool)              # one fresh re-download\n    else:\n        raise","preventionTips":["Prefer sha256-pinned registry entries: corrupt downloads fail the hash check before extraction.","Monitor cache-volume disk space; ENOSPC during extraction surfaces as this error.","If a mirror is in use, verify it serves binary-identical assets, not re-packed ones."],"tags":["python","binaries","extraction","archive","corruption","disk-full"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}