headroomlabs-ai/headroom · error · RuntimeError

Unsupported platform: {system} {machine}

Error message

Unsupported platform: {system} {machine}

What it means

Raised by _detect_platform in headroom.graph.installer when platform.system()/platform.machine() return a combination outside darwin/linux/windows. The installer maps the host OS+arch to a release asset suffix (darwin-arm64, linux-amd64, ...) for the codebase-memory-mcp binary; anything unmappable (e.g. FreeBSD, a exotic musl container reporting oddly, or mocked platform values in tests) aborts before any download.

Source

Thrown at headroom/graph/installer.py:38

GITHUB_RELEASE_URL = f"https://github.com/{CBM_REPO}/releases/download"


def _detect_platform() -> str:
    """Detect platform and return the release asset suffix."""
    system = platform.system().lower()
    machine = platform.machine().lower()

    if system == "darwin":
        arch = "arm64" if machine == "arm64" else "amd64"
        return f"darwin-{arch}"
    elif system == "linux":
        arch = "arm64" if machine in ("aarch64", "arm64") else "amd64"
        return f"linux-{arch}"
    elif system == "windows":
        return "windows-amd64"

    raise RuntimeError(f"Unsupported platform: {system} {machine}")


def get_cbm_path() -> Path | None:
    """Find codebase-memory-mcp binary, return path or None."""
    # Check PATH first
    found = shutil.which(CBM_BIN_NAME)
    if found:
        return Path(found)

    # Check our install location
    installed = CBM_BIN_DIR / CBM_BIN_NAME
    if installed.exists() and installed.is_file():
        return installed

    return None


def download_cbm(version: str | None = None) -> Path:

View on GitHub (pinned to 322425c43b)

Solutions

1. Run on a supported platform (macOS, Linux, Windows) — check platform.system() first to see what your host reports.
2. If the binary exists for your arch under a different name, pre-install codebase-memory-mcp on PATH (get_cbm_path checks PATH first) so the downloader never runs.
3. On unusual Linux arch names, verify with uname -m; if it is not aarch64/arm64 the code assumes amd64, so ensure an amd64 binary is actually correct.
4. For truly unsupported systems, disable/skip the graph feature rather than calling the installer.

Example fix

# before
# on FreeBSD: installer fails 'Unsupported platform: freebsd amd64'

# after: pre-install the binary so detection is bypassed
$ cp codebase-memory-mcp ~/.local/bin/ && export PATH="$HOME/.local/bin:$PATH"

import platform

system, machine = platform.system().lower(), platform.machine().lower()
if system not in ("darwin", "linux", "windows"):
    raise SystemExit(f"CBM installer unsupported on {system} {machine}; "
                     "pre-install the binary on PATH instead")

def platform_supported_for_cbm() -> bool:
    return platform.system().lower() in {"darwin", "linux", "windows"}

try:
    install_cbm()
except RuntimeError as e:
    if str(e).startswith("Unsupported platform"):
        logger.warning("skipping CBM install: %s", e)
    else:
        raise

When it happens

Trigger: Running the CBM installer flow (install/ensure of codebase-memory-mcp) on an OS whose platform.system() is 'freebsd', 'sunos', 'java' (Jython), or empty; occasionally on heavily stripped containers where platform detection misbehaves. Linux aarch64/arm64, x86_64, darwin arm64/other, and windows are all handled.

Common situations: Trying headroom's graph/CBM features on BSD or a niche VM; cross-compiling environments; test harnesses that monkeypatch platform; ARM Linux variants reporting machine names other than aarch64/arm64 (they fall back to amd64, which then mismatches the real arch at runtime).

Related errors

• {tool}: no prebuilt binary for {plat.key()}; supported: {sup
• offline mode (HEADROOM_BINARIES_OFFLINE=1) but fetch require
• OPENAI_API_KEY environment variable required
• Invalid URL: {url}
• Failed to download codebase-memory-mcp from {url}: {e}

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