headroomlabs-ai/headroom · error · KeyError

unknown tool {tool!r}; known: {sorted(tools)}

Error message

unknown tool {tool!r}; known: {sorted(tools)}

What it means

_tool_entry raises KeyError when the requested tool name is not a key in the 'tools' object of the bundled registry JSON (loaded once via lru_cache from _REGISTRY_PATH). The message lists the exact sorted set of known tool names, so a typo is immediately visible.

Source

Thrown at headroom/binaries.py:198

# ---------- Registry ------------------------------------------------------ #


_REGISTRY_PATH = Path(__file__).parent / "tools.json"


@functools.lru_cache(maxsize=1)
def _registry() -> dict[str, Any]:
    with _REGISTRY_PATH.open("r", encoding="utf-8") as f:
        data: dict[str, Any] = json.load(f)
    return data


def _tool_entry(tool: str) -> dict[str, Any]:
    reg = _registry()
    tools: dict[str, Any] = reg.get("tools", {})
    if tool not in tools:
        raise KeyError(f"unknown tool {tool!r}; known: {sorted(tools)}")
    entry: dict[str, Any] = tools[tool]
    return entry


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())

View on GitHub (pinned to 322425c43b)

Solutions

1. Read the 'known:' list in the error message and use one of those exact names.
2. If the tool should exist, upgrade (or pin) headroom-ai to the release whose registry contains it.
3. Inspect the registry directly: python -c "from headroom.binaries import _registry; print(sorted(_registry()['tools']))".
4. If adding a new tool, add its entry to the registry JSON instead of calling with an unregistered name.

Example fix

# before
ensure_binary("difftastic")

# after
ensure_binary("difft")  # exact name from the registry's known list

from headroom.binaries import _registry

def known_tools() -> set[str]:
    return set(_registry()["tools"])

def is_known_tool(name: str) -> bool:
    return name in known_tools()

assert is_known_tool("difft"), f"pick from {sorted(known_tools())}"

def is_known_tool(tool: object) -> bool:
    return isinstance(tool, str) and tool in _registry().get("tools", {})

try:
    entry = _tool_entry(tool)
except KeyError as e:
    logger.error("tool not in registry: %s; known: %s", tool, sorted(_registry()["tools"]))
    raise

When it happens

Trigger: Calling any registry-backed helper (_is_pypi_tool, _asset_for_platform, and the public ensure/install APIs) with a misspelled or version-removed tool name, e.g. 'difftastic' instead of 'difft'.

Common situations: Typos, passing an executable path instead of the registry tool name, or referencing a tool that exists only in a newer/older headroom-ai release's registry than the installed one.

Related errors

• archive did not contain expected member {member!r}
• neither `objdump` nor `llvm-objdump` is on PATH; install bin
• items_json must be JSON: {e}
• items_json must be a JSON array, got {}
• doc_json must be JSON: {e}

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