usestrix/strix · error · RuntimeError

Go 1.24 or newer is required to build the Bubble Tea TUI

Error message

Go 1.24 or newer is required to build the Bubble Tea TUI

What it means

Raised by the Hatchling build hook (scripts/tui_sidecar_hook.py) when a wheel build cannot find a Go toolchain on PATH. Strix bundles its Bubble Tea TUI sidecar (strix-tui) into every wheel, so a missing Go compiler is a hard build failure, not a warning. Editable installs skip this hook because they run the TUI via `go run` from the checkout.

Source

Thrown at scripts/tui_sidecar_hook.py:35

    The sidecar is the only interactive interface, so every wheel is a
    platform wheel and a missing Go toolchain is a build failure.
    """

    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
        # Editable installs run from the checkout, where the TUI is started
        # with ``go run``; there is nothing to bundle.
        if version == "editable":
            return

        root = Path(self.root)
        executable = "strix-tui.exe" if os.name == "nt" else "strix-tui"
        output = root / "build" / "sidecar" / executable
        output.parent.mkdir(parents=True, exist_ok=True)

        go = shutil.which("go")
        if go is None:
            raise RuntimeError("Go 1.24 or newer is required to build the Bubble Tea TUI")
        env = os.environ.copy()
        env["CGO_ENABLED"] = "0"
        subprocess.run(  # noqa: S603 - fixed build command using the resolved Go binary
            [
                go,
                "build",
                "-trimpath",
                "-ldflags=-s -w",
                "-o",
                str(output),
                "./cmd/strix-tui",
            ],
            cwd=root / "strix" / "interface" / "tui",
            env=env,
            check=True,
        )

        build_data["force_include"][str(output)] = f"strix/bin/{executable}"

View on GitHub (pinned to 8551339130)

Solutions

Install Go 1.24+ (e.g. download from go.dev/dl or use actions/setup-go with go-version: '>=1.24') and confirm `go version` works in the same shell/CI step that builds the wheel
Ensure the Go bin directory (e.g. /usr/local/go/bin) is on PATH for the build process — in Dockerfiles use ENV PATH=$PATH:/usr/local/go/bin
For local development use an editable install (`pip install -e .`) which skips the sidecar build entirely and runs the TUI via `go run`
In CI, cache the Go module cache (GOPATH/pkg/mod) to speed up repeated sidecar builds

Example fix

# before (CI job with only Python installed)
- run: pip install strix
# after
- uses: actions/setup-go@v5
  with:
    go-version: '1.24'
- run: pip install strix

Defensive patterns

Strategy: validation

Validate before calling

import shutil, subprocess

def go_toolchain_ok(min_minor: int = 24) -> bool:
    go = shutil.which("go")
    if go is None:
        return False
    out = subprocess.run([go, "version"], capture_output=True, text=True).stdout  # e.g. go version go1.24.1 linux/amd64
    try:
        minor = int(out.split()[2].split(".")[1])
    except (IndexError, ValueError):
        return False
    return minor >= min_minor

assert go_toolchain_ok(), "Install Go 1.24+ and put it on PATH before building the wheel"

Prevention

Install Go via the official installer or setup-go action and verify `go version` in the same CI step that builds the wheel
Use `pip install -e .` for development — the sidecar build is skipped and the TUI runs via `go run`
Add a pre-build check for the Go toolchain in CI so the failure message names the missing prerequisite

When it happens

Trigger: Running `pip wheel .`, `python -m build`, `hatch build`, or `pip install .` (non-editable) in an environment where `shutil.which("go")` returns None — i.e. the `go` binary is not on PATH.

Common situations: CI images (python:* Docker images, GitHub Actions ubuntu-latest without a setup-go step) that only install Python; installing from sdist on a machine where Go was installed via a tarball but not added to PATH; shell environments where GOPATH/bin or /usr/local/go/bin was never exported.

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/d8ea27e23fddc0f5. Report an issue: GitHub.