headroomlabs-ai/headroom · critical · SystemExit

Proxy process exited unexpectedly.

Error message

Proxy process exited unexpectedly.

What it means

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.

Source

Thrown at headroom/cli/wrap.py:2990

        )
        if actual_port != port:
            _unregister_proxy_client(port)
            _register_proxy_client(actual_port)
        port_holder[0] = actual_port
        _push_runtime_env(actual_port, no_proxy)
        click.echo()
        print_setup_lines(actual_port)
        click.echo()
        click.echo("  Press Ctrl+C to stop the proxy.")
        click.echo()

        try:
            while True:
                time.sleep(1)
                proc = proxy_holder[0]
                if proc and proc.poll() is not None:
                    click.echo("  Proxy process exited unexpectedly.")
                    raise SystemExit(1)
        except KeyboardInterrupt:
            click.echo("\n  Shutting down...")
    except SystemExit:
        raise
    except Exception as e:
        click.echo(f"  Error: {e}")
        raise SystemExit(1) from e
    finally:
        cleanup()


def _inject_memory_mcp_config(user_id: str) -> None:
    """Register headroom memory as an MCP server in Codex's config.toml.

    Idempotent — replaces existing section if present.
    """
    import sys

View on GitHub (pinned to 322425c43b)

Solutions

1. Inspect the proxy log (log_dir()/proxy.log) to find why the child terminated
2. If OOM (dmesg shows kill), reduce memory pressure or restart the session with a lighter backend/config
3. Update Headroom — mid-session proxy crashes on specific requests are bug-fixed over time; report with the log tail if persistent
4. Simply rerun `headroom wrap <tool>`; if it crashes reproducibly on the same action, capture that request as a bug report

try:
    run_wrap_foreground()
except SystemExit as e:
    if e.code == 1 and proxy_died():
        log.error("proxy died mid-session; see %s", log_dir() / "proxy.log")
        # restart policy: relaunch the wrap once, else surface to the user
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Proxy exited with code {proc.returncode}: {tail}
• Error: Proxy dependencies not installed. Run: pip install he
• Shutting down...
• No available port found in range {start_port}-{end_port - 1}
• Proxy failed to start on port {port} within {timeout_seconds

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/239f04d8860f3f74. Report an issue: GitHub.