headroomlabs-ai/headroom · error · PlatformNotSupported

{tool}: no prebuilt binary for {plat.key()}; supported: {sup

Error message

{tool}: no prebuilt binary for {plat.key()}; supported: {supported}

What it means

_asset_for_platform raises PlatformNotSupported when the tool has downloadable assets but none matches the current PlatformKey. The message lists the sorted set of platform keys that ARE supported, so you can immediately see whether your platform (e.g. linux-arm64, macos-aarch64) was ever shipped.

Source

Thrown at headroom/binaries.py:219

def _is_pypi_tool(tool: str) -> bool:
    entry = _tool_entry(tool)
    return entry.get("version") == "pypi" or not entry.get("assets")


def _asset_for_platform(tool: str, plat: PlatformKey) -> dict[str, Any]:
    entry = _tool_entry(tool)
    if _is_pypi_tool(tool):
        raise PlatformNotSupported(
            f"{tool}: distributed via PyPI only; `pip install headroom-ai` "
            f"should have placed `{entry.get('binary', tool)}` on PATH."
        )
    assets: dict[str, Any] = entry.get("assets", {})
    asset: dict[str, Any] | None = assets.get(plat.key())
    if asset is None:
        supported = sorted(assets.keys())
        raise PlatformNotSupported(
            f"{tool}: no prebuilt binary for {plat.key()}; supported: {supported}"
        )
    return asset


def _mirror_url(url: str) -> str:
    mirror = os.environ.get("HEADROOM_BINARIES_MIRROR")
    if not mirror:
        return url
    # Only substitute the github.com host so that paths remain intact.
    for prefix in ("https://github.com", "https://objects.githubusercontent.com"):
        if url.startswith(prefix):
            return mirror.rstrip("/") + url[len(prefix) :]
    return url


# ---------- Download + verify --------------------------------------------- #

View on GitHub (pinned to 322425c43b)

Solutions

1. Compare your platform key against the 'supported:' list in the message.
2. Upgrade headroom-ai — newer registries often add platforms (e.g. aarch64) that older ones lack.
3. If no release exists for your platform, install the tool manually (cargo install, brew, apt) and place it on PATH so the fetch path is bypassed.
4. On Alpine, prefer a glibc-based image (debian-slim) if only glibc assets exist.

Example fix

# before: running on linux-aarch64, tool ships only x86_64
# PlatformNotSupported: no prebuilt binary for linux-aarch64

# after: pre-provision the tool in the image
RUN apt-get install -y difftastic  # or cargo install difftastic

import platform

def platform_supported(tool: str) -> bool:
    from headroom.binaries import _registry, _tool_entry, _is_pypi_tool, PlatformKey
    if _is_pypi_tool(tool):
        return True
    plat = PlatformKey.current()  # or however the caller derives it
    return plat.key() in _tool_entry(tool).get("assets", {})

if not platform_supported("difft"):
    raise SystemExit("no prebuilt difft for this platform; install it manually")

try:
    ensure_binary("difft")
except PlatformNotSupported as e:
    logger.warning("%s; pre-provisioning via system package manager", e)
    subprocess.run(["apt-get", "install", "-y", "difftastic"], check=True)

When it happens

Trigger: Running on an OS/architecture combination absent from the registry's assets map for that tool — e.g. linux musl, an uncommon architecture, or a platform added in a newer release than the installed registry.

Common situations: Alpine/musl images, ARM servers or Apple Silicon when the tool only published x86_64 builds, or an outdated headroom-ai whose registry predates a platform's release.

Related errors

• {tool}: distributed via PyPI only; `pip install headroom-ai`
• offline mode (HEADROOM_BINARIES_OFFLINE=1) but fetch require
• binary cache directory parent is not writable: {dest.parent}
• binary cache directory is not writable: {dest.parent}
• failed to download {final_url} after {attempts} attempts: {e

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