{"record":{"id":"67a59948250cdd08","repo":"usestrix/strix","slug":"bubble-tea-tui-exited-with-status-return-code","errorCode":null,"errorMessage":"Bubble Tea TUI exited with status {return_code}","messagePattern":"Bubble Tea TUI exited with status (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"strix/interface/tui/sidecar.py","lineNumber":182,"sourceCode":"        listener.bind((\"127.0.0.1\", 0))\n        listener.listen(1)\n        token = secrets.token_hex(32)\n        host, port = listener.getsockname()[:2]\n        env.update({\"STRIX_TUI_ADDR\": f\"{host}:{port}\", \"STRIX_TUI_TOKEN\": token})\n        windows_process = subprocess.Popen(command, env=env, cwd=cwd)  # noqa: S603\n        connection = await asyncio.to_thread(_accept_authenticated_connection, listener, token)\n    except BaseException:\n        await terminate_process(windows_process)\n        raise\n    finally:\n        listener.close()\n    assert windows_process is not None and connection is not None\n    return windows_process, connection\n\n\ndef check_return_code(return_code: int) -> None:\n    if return_code != 0:\n        raise RuntimeError(f\"Bubble Tea TUI exited with status {return_code}\")\n\n\ndef package_version() -> str:\n    \"\"\"Report the installed package version for the Go splash/stats\n    (\"dev\" when metadata is unavailable).\"\"\"\n    try:\n        return version(\"strix-agent\")\n    except PackageNotFoundError:\n        return \"dev\"\n","sourceCodeStart":164,"sourceCodeEnd":192,"githubUrl":"https://github.com/usestrix/strix/blob/85513391305171ecc6faffe03da4a8bda5e3febb/strix/interface/tui/sidecar.py#L164-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run in a real, capable terminal (not a piped/non-TTY CI shell); verify TERM is set (e.g. export TERM=xterm-256color)","Reinstall from an official wheel so the Go binary matches the Python backend version","Capture the TUI process stderr/stdout around the failure to find the Go-side panic or message that preceded exit","Update terminfo on old distros; try a different terminal emulator to rule out render bugs","Report with the exact status code if it persists after a clean reinstall"],"exampleFix":"# before\nTERM= strix  # TUI exits status 2 -> RuntimeError\n\n# after\nexport TERM=xterm-256color\nstrix","handlingStrategy":"try-catch","validationCode":"import sys, os\nif not sys.stdout.isatty():\n    raise SystemExit(\"run the TUI in an interactive terminal\")\nos.environ.setdefault(\"TERM\", \"xterm-256color\")","typeGuard":"def terminal_ok() -> bool:\n    return sys.stdout.isatty() and bool(os.environ.get(\"TERM\"))","tryCatchPattern":"try:\n    await run_tui()\nexcept RuntimeError as e:\n    m = re.search(r\"exited with status (\\d+)\", str(e))\n    if m:\n        log_tui_output_for_bug(int(m.group(1)))  # capture frontend stderr, check TERM, reinstall\n    else:\n        raise","preventionTips":["Run in a real TTY with TERM set; avoid piping the TUI","Keep Python backend and Go binary versions in sync (reinstall together)","Preserve the subprocess stderr so Go panics are diagnosable"],"tags":["tui","go","subprocess","terminal"],"backgroundTag":null,"analyzedSha":"85513391305171ecc6faffe03da4a8bda5e3febb","analyzedAt":"2026-08-15T05:03:57.275Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}