headroomlabs-ai/headroom · error · SystemExit

{wheel.name} does not contain headroom/_core native extensio

Error message

{wheel.name} does not contain headroom/_core native extension

What it means

verify_wheel() opens the built wheel and requires at least one compiled extension module under `headroom/_core` (a `.so` or `.pyd` file). This project is a PyO3/Rust extension shipped as a wheel, so a wheel without a native module means the Python package would silently fall back to nothing at runtime — the smoke test blocks that.

Source

Thrown at scripts/build_python_release_smoke.py:103

def find_one_artifact(out_dir: Path, pattern: str) -> Path:
    matches = sorted(out_dir.glob(pattern))
    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:

View on GitHub (pinned to 322425c43b)

Solutions

1. Open the wheel (`unzip -l wheel/*.whl | grep headroom/_core`) and check where the extension actually landed; adjust the verify prefix if the layout legitimately changed.
2. Confirm the build used `maturin build`, not `pip wheel` or `python -m build`, so the Rust extension is compiled in.
3. Check the Cargo build log for errors and that the Rust toolchain is installed (`cargo --version`).
4. Verify the pyo3 module config in pyproject/Cargo.toml still names the module `_core` inside the `headroom` package.

import zipfile

def wheel_has_native_ext(wheel_path: str, prefix: str = "headroom/_core") -> bool:
    with zipfile.ZipFile(wheel_path) as z:
        return any(
            n.startswith(prefix) and n.rsplit(".", 1)[-1].lower() in {"so", "pyd"}
            for n in z.namelist()
        )

When it happens

Trigger: Building the wheel without the Rust extension compiling (maturin succeeded but the extension module was skipped or renamed); the package layout changed so the extension lives somewhere other than `headroom/_core`; building a pure-Python wheel by accident (e.g., `python -m build --wheel` on the Python package instead of `maturin build`).

Common situations: Cargo/Rust toolchain missing in CI so the extension is never produced; module path renamed in pyo3 config (`name = "_core"` under a different package); abi3 forward compatibility producing a differently-suffixed file; wheel built from the sdist re-packaged by a non-maturin builder.

Related errors

• expected exactly one {pattern} in {out_dir}, found {len(matc
• items_json must be JSON: {e}
• items_json must be a JSON array, got {}
• doc_json must be JSON: {e}
• unknown importance context: {context}

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