{"record":{"id":"239f04d8860f3f74","repo":"headroomlabs-ai/headroom","slug":"proxy-process-exited-unexpectedly","errorCode":null,"errorMessage":"Proxy process exited unexpectedly.","messagePattern":"Proxy process exited unexpectedly\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"critical","filePath":"headroom/cli/wrap.py","lineNumber":2990,"sourceCode":"        )\n        if actual_port != port:\n            _unregister_proxy_client(port)\n            _register_proxy_client(actual_port)\n        port_holder[0] = actual_port\n        _push_runtime_env(actual_port, no_proxy)\n        click.echo()\n        print_setup_lines(actual_port)\n        click.echo()\n        click.echo(\"  Press Ctrl+C to stop the proxy.\")\n        click.echo()\n\n        try:\n            while True:\n                time.sleep(1)\n                proc = proxy_holder[0]\n                if proc and proc.poll() is not None:\n                    click.echo(\"  Proxy process exited unexpectedly.\")\n                    raise SystemExit(1)\n        except KeyboardInterrupt:\n            click.echo(\"\\n  Shutting down...\")\n    except SystemExit:\n        raise\n    except Exception as e:\n        click.echo(f\"  Error: {e}\")\n        raise SystemExit(1) from e\n    finally:\n        cleanup()\n\n\ndef _inject_memory_mcp_config(user_id: str) -> None:\n    \"\"\"Register headroom memory as an MCP server in Codex's config.toml.\n\n    Idempotent — replaces existing section if present.\n    \"\"\"\n    import sys\n","sourceCodeStart":2972,"sourceCodeEnd":3008,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L2972-L3008","documentation":"In the wrap foreground/monitor loop, Headroom sleeps 1 second at a time and checks the proxy subprocess (held in proxy_holder[0]). If the child process terminates while the monitor loop is running, Headroom prints 'Proxy process exited unexpectedly.' and raises SystemExit(1). This is a user-facing CLI message, not an exception with recovery context — the proxy died mid-session.","triggerScenarios":"Running `headroom wrap <tool>` in monitor mode where the proxy child crashes after a healthy start: OOM kill, unhandled exception in the proxy server on a specific request, the child being killed externally (kill -9, container OOM), or a fatal error in the selected backend connection.","commonSituations":"Long coding sessions where the proxy leaks memory until the OOM killer reaps it; proxy hitting an unhandled exception on an unusual request shape; system sleep/resume killing the child; another process or cleanup script killing processes matching the proxy's name.","solutions":["Inspect the proxy log (log_dir()/proxy.log) to find why the child terminated","If OOM (dmesg shows kill), reduce memory pressure or restart the session with a lighter backend/config","Update Headroom — mid-session proxy crashes on specific requests are bug-fixed over time; report with the log tail if persistent","Simply rerun `headroom wrap <tool>`; if it crashes reproducibly on the same action, capture that request as a bug report"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    run_wrap_foreground()\nexcept SystemExit as e:\n    if e.code == 1 and proxy_died():\n        log.error(\"proxy died mid-session; see %s\", log_dir() / \"proxy.log\")\n        # restart policy: relaunch the wrap once, else surface to the user\n    raise","preventionTips":["Monitor memory use of the proxy during long sessions; restart on growth","Keep proxy.log accessible so mid-session crashes are diagnosable","Wrap sessions in a supervisor (e.g. tmux + health check) if you need auto-restart"],"tags":["proxy","process-crash","monitoring","logging","headroom","cli"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}