usestrix/strix · critical · RuntimeError

Bubble Tea TUI binary not found. Reinstall Strix from an off

Error message

Bubble Tea TUI binary not found. Reinstall Strix from an official platform wheel.

What it means

Raised by TuiRuntime.binary_command (runtime.py:321) when it can find neither a Go toolchain to run the TUI from source (tui_source_dir contains go.mod and `go` is on PATH) nor a packaged Bubble Tea binary under the installed wheel's resources (get_strix_resource_path('bin', tui_executable())). It means the current installation is incomplete: a pip/source install that never bundled the Go frontend.

Source

Thrown at strix/interface/tui/runtime.py:321

        self.coordinator.mark_shutting_down()
        scan_task = self.scan_task
        if scan_task is not None:
            if not scan_task.done():
                scan_task.cancel()
            with contextlib.suppress(asyncio.CancelledError):
                await scan_task

    @staticmethod
    def binary_command() -> list[str]:
        source = tui_source_dir()
        # A checkout may also contain a stale wheel/build sidecar. Running the
        # current source is the deterministic development choice.
        if (source / "go.mod").is_file() and shutil.which("go"):
            return ["go", "run", "./cmd/strix-tui"]
        packaged = get_strix_resource_path("bin", tui_executable())
        if packaged.is_file():
            return [str(packaged)]
        raise RuntimeError(
            "Bubble Tea TUI binary not found. Reinstall Strix from an official platform wheel."
        )

    @staticmethod
    async def _cancel_tasks(*tasks: asyncio.Task[None] | None) -> None:
        for task in tasks:
            if task is None:
                continue
            task.cancel()
            with contextlib.suppress(asyncio.CancelledError):
                await task

    async def run(self) -> None:
        # Redirect the process's sys.stdout/sys.stderr while the TUI runs so
        # logging handlers created during the scan never paint over the Go
        # TUI's alt screen. The child still inherits the real terminal fds;
        # only the Python-level bindings change.
        original_stdout = sys.stdout

View on GitHub (pinned to 8551339130)

Solutions

1. Reinstall from an official platform wheel: pip install --force-reinstall strix-agent (wheel bundles bin/<tui executable>)
2. For source development: install Go (https://go.dev) and ensure `go` is on PATH so 'go run ./cmd/strix-tui' is used
3. Verify the resource dir contains bin/<executable> after install; if not, the wheel is wrong for your platform
4. Check tui_executable() output matches a file in the package's bin directory

Example fix

# before
pip install strix-agent==x.y.z  # sdist without bundled binary
strix  # RuntimeError: Bubble Tea TUI binary not found

# after
pip install --force-reinstall strix-agent==x.y.z \
  --only-binary :all:  # enforce platform wheel
strix

cmd = None
src = tui_source_dir()
if (src / "go.mod").is_file() and shutil.which("go"):
    cmd = ["go", "run", "./cmd/strix-tui"]
else:
    packaged = get_strix_resource_path("bin", tui_executable())
    if packaged.is_file():
        cmd = [str(packaged)]
if cmd is None:
    install_official_wheel_or_go()

def tui_runtime_available() -> bool:
    src = tui_source_dir()
    if (src / "go.mod").is_file() and shutil.which("go"):
        return True
    return get_strix_resource_path("bin", tui_executable()).is_file()

try:
    cmd = TuiRuntime.binary_command()
except RuntimeError as e:
    if "binary not found" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "--force-reinstall", "--only-binary", ":all:", "strix-agent"], check=True)
        cmd = TuiRuntime.binary_command()
    else:
        raise

When it happens

Trigger: Running the TUI from a pip install built without the Go binary step, or from a source checkout after deleting the Go module or with Go uninstalled, or on a platform with no prebuilt wheel (binary resource missing). tui_executable() names the platform binary that is absent.

Common situations: pip install from sdist/PyPI source distribution that lacks the bundled bin; installing on an uncommon platform/arch with no wheel; Go removed from PATH after a source checkout; a venv copied or relocated so resource paths broke.

Related errors

• Go 1.24 or newer is required to build the Bubble Tea TUI
• Bubble Tea TUI exited with status {return_code}
• The interactive interface could not start: {exc}
• Unknown command: {command}
• instruction must be a string

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