usestrix/strix · error · RuntimeError

Bubble Tea TUI exited with status {return_code}

Error message

Bubble Tea TUI exited with status {return_code}

What it means

Raised by check_return_code (sidecar.py:182), called from runtime.py:368 when the spawned Bubble Tea TUI process exits with a non-zero status. The status code is interpolated into the message. Any crash of the Go frontend — panic, render failure, IPC protocol error, or early exit during startup — surfaces here.

Source

Thrown at strix/interface/tui/sidecar.py:182

        listener.bind(("127.0.0.1", 0))
        listener.listen(1)
        token = secrets.token_hex(32)
        host, port = listener.getsockname()[:2]
        env.update({"STRIX_TUI_ADDR": f"{host}:{port}", "STRIX_TUI_TOKEN": token})
        windows_process = subprocess.Popen(command, env=env, cwd=cwd)  # noqa: S603
        connection = await asyncio.to_thread(_accept_authenticated_connection, listener, token)
    except BaseException:
        await terminate_process(windows_process)
        raise
    finally:
        listener.close()
    assert windows_process is not None and connection is not None
    return windows_process, connection


def check_return_code(return_code: int) -> None:
    if return_code != 0:
        raise RuntimeError(f"Bubble Tea TUI exited with status {return_code}")


def package_version() -> str:
    """Report the installed package version for the Go splash/stats
    ("dev" when metadata is unavailable)."""
    try:
        return version("strix-agent")
    except PackageNotFoundError:
        return "dev"

View on GitHub (pinned to 8551339130)

Solutions

1. Run in a real, capable terminal (not a piped/non-TTY CI shell); verify TERM is set (e.g. export TERM=xterm-256color)
2. Reinstall from an official wheel so the Go binary matches the Python backend version
3. Capture the TUI process stderr/stdout around the failure to find the Go-side panic or message that preceded exit
4. Update terminfo on old distros; try a different terminal emulator to rule out render bugs
5. Report with the exact status code if it persists after a clean reinstall

Example fix

# before
TERM= strix  # TUI exits status 2 -> RuntimeError

# after
export TERM=xterm-256color
strix

import sys, os
if not sys.stdout.isatty():
    raise SystemExit("run the TUI in an interactive terminal")
os.environ.setdefault("TERM", "xterm-256color")

def terminal_ok() -> bool:
    return sys.stdout.isatty() and bool(os.environ.get("TERM"))

try:
    await run_tui()
except RuntimeError as e:
    m = re.search(r"exited with status (\d+)", str(e))
    if m:
        log_tui_output_for_bug(int(m.group(1)))  # capture frontend stderr, check TERM, reinstall
    else:
        raise

When it happens

Trigger: The Go TUI subprocess exits non-zero: terminal does not support required capabilities, a protocol/message shape from the Python side crashed the frontend, the binary segfaults, or the user's terminal closed abruptly. check_return_code(return_code) is invoked on process completion.

Common situations: Running under a minimal terminal (CI without TTY, very old terminfo); version mismatch between the Python backend and a stale packaged Go binary after a partial upgrade; TERM unset/garbage; a Go panic triggered by unexpected input; running inside environments that send odd escape sequences.

Related errors

• The interactive interface could not start: {exc}
• Bubble Tea TUI binary not found. Reinstall Strix from an off
• Go 1.24 or newer is required to build the Bubble Tea TUI
• Unknown command: {command}
• instruction must be a string

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