headroomlabs-ai/headroom · error · SystemExit

{wheel.name} should contain exactly one dist-info/METADATA,

Error message

{wheel.name} should contain exactly one dist-info/METADATA, found {len(metadata_members)}

What it means

verify_wheel() requires the wheel to contain exactly one `*.dist-info/METADATA` member. Zero means the wheel is malformed (no metadata at all); more than one means two dist-info directories got merged in, which breaks installers. Well-formed wheels built by maturin/pip always have exactly one.

Source

Thrown at scripts/build_python_release_smoke.py:107

    if len(matches) != 1:
        raise SystemExit(f"expected exactly one {pattern} in {out_dir}, found {len(matches)}")
    return matches[0]


def verify_wheel(wheel: Path, expected_version: str) -> None:
    with zipfile.ZipFile(wheel) as archive:
        names = set(archive.namelist())
        native_members = [
            name
            for name in names
            if name.startswith("headroom/_core") and Path(name).suffix.lower() in {".pyd", ".so"}
        ]
        if not native_members:
            raise SystemExit(f"{wheel.name} does not contain headroom/_core native extension")

        metadata_members = [name for name in names if name.endswith(".dist-info/METADATA")]
        if len(metadata_members) != 1:
            raise SystemExit(
                f"{wheel.name} should contain exactly one dist-info/METADATA, "
                f"found {len(metadata_members)}"
            )
        metadata = archive.read(metadata_members[0]).decode("utf-8")

    expected_line = f"Version: {expected_version}"
    if expected_line not in metadata.splitlines():
        raise SystemExit(f"{wheel.name} metadata missing {expected_line!r}")

    print(f"wheel metadata OK: {wheel.name} contains {native_members[0]}")


def verify_sdist_license_files(sdist: Path) -> None:
    with tarfile.open(sdist, "r:gz") as archive:
        names = set(archive.getnames())
        roots = {name.split("/", 1)[0] for name in names if "/" in name}
        if len(roots) != 1:
            raise SystemExit(f"expected one sdist root directory, found {sorted(roots)}")

View on GitHub (pinned to 322425c43b)

Solutions

List the wheel members (`unzip -l file.whl | grep dist-info`) and remove the duplicate dist-info if one was injected.
Rebuild the wheel from scratch in a clean output directory.
If corruption recurs, check disk space and network transfer of the artifact.

Defensive patterns

Strategy: validation

Validate before calling

import zipfile

def wheel_metadata_count(wheel_path: str) -> int:
    with zipfile.ZipFile(wheel_path) as z:
        return sum(1 for n in z.namelist() if n.endswith(".dist-info/METADATA"))

Prevention

Do not post-process wheels by re-zipping manually; rebuild with the packaging tool.
Treat a failed check as corruption and rebuild rather than patching the archive.
Check disk space in CI — truncated zips are a classic full-disk symptom.

When it happens

Trigger: A corrupted or hand-assembled zip; merging two wheels' contents into one archive; a partially written wheel from an interrupted build.

Common situations: Disk-full or killed maturin producing a truncated zip; post-processing scripts that rewrite the wheel and accidentally duplicate dist-info; downloading the artifact through a flaky proxy corrupting the archive.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/8939499d0342bf25. Report an issue: GitHub.