{"record":{"id":"eba2084573574447","repo":"headroomlabs-ai/headroom","slug":"tool-no-prebuilt-binary-for-plat-key-suppo","errorCode":null,"errorMessage":"{tool}: no prebuilt binary for {plat.key()}; supported: {supported}","messagePattern":"(.+?): no prebuilt binary for (.+?); supported: (.+?)","errorType":"exception","errorClass":"PlatformNotSupported","httpStatus":null,"severity":"error","filePath":"headroom/binaries.py","lineNumber":219,"sourceCode":"\n\ndef _is_pypi_tool(tool: str) -> bool:\n    entry = _tool_entry(tool)\n    return entry.get(\"version\") == \"pypi\" or not entry.get(\"assets\")\n\n\ndef _asset_for_platform(tool: str, plat: PlatformKey) -> dict[str, Any]:\n    entry = _tool_entry(tool)\n    if _is_pypi_tool(tool):\n        raise PlatformNotSupported(\n            f\"{tool}: distributed via PyPI only; `pip install headroom-ai` \"\n            f\"should have placed `{entry.get('binary', tool)}` on PATH.\"\n        )\n    assets: dict[str, Any] = entry.get(\"assets\", {})\n    asset: dict[str, Any] | None = assets.get(plat.key())\n    if asset is None:\n        supported = sorted(assets.keys())\n        raise PlatformNotSupported(\n            f\"{tool}: no prebuilt binary for {plat.key()}; supported: {supported}\"\n        )\n    return asset\n\n\ndef _mirror_url(url: str) -> str:\n    mirror = os.environ.get(\"HEADROOM_BINARIES_MIRROR\")\n    if not mirror:\n        return url\n    # Only substitute the github.com host so that paths remain intact.\n    for prefix in (\"https://github.com\", \"https://objects.githubusercontent.com\"):\n        if url.startswith(prefix):\n            return mirror.rstrip(\"/\") + url[len(prefix) :]\n    return url\n\n\n# ---------- Download + verify --------------------------------------------- #\n","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/binaries.py#L201-L237","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Compare your platform key against the 'supported:' list in the message.","Upgrade headroom-ai — newer registries often add platforms (e.g. aarch64) that older ones lack.","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.","On Alpine, prefer a glibc-based image (debian-slim) if only glibc assets exist."],"exampleFix":"# before: running on linux-aarch64, tool ships only x86_64\n# PlatformNotSupported: no prebuilt binary for linux-aarch64\n\n# after: pre-provision the tool in the image\nRUN apt-get install -y difftastic  # or cargo install difftastic","handlingStrategy":"validation","validationCode":"import platform\n\ndef platform_supported(tool: str) -> bool:\n    from headroom.binaries import _registry, _tool_entry, _is_pypi_tool, PlatformKey\n    if _is_pypi_tool(tool):\n        return True\n    plat = PlatformKey.current()  # or however the caller derives it\n    return plat.key() in _tool_entry(tool).get(\"assets\", {})\n\nif not platform_supported(\"difft\"):\n    raise SystemExit(\"no prebuilt difft for this platform; install it manually\")","typeGuard":null,"tryCatchPattern":"try:\n    ensure_binary(\"difft\")\nexcept PlatformNotSupported as e:\n    logger.warning(\"%s; pre-provisioning via system package manager\", e)\n    subprocess.run([\"apt-get\", \"install\", \"-y\", \"difftastic\"], check=True)","preventionTips":["Build images on the same arch they deploy on (or use multi-arch builds).","Pre-install platform-missing tools in the base image so the fetch path never runs.","Check the registry's supported list before adding a tool to a new platform target."],"tags":["python","binaries","platform","architecture","platform-not-supported"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}