headroomlabs-ai/headroom · error · SystemExit

Error: {e}

Error message

Error: {e}

What it means

This is the top-level catch-all of the wrap launch path: any exception that is not SystemExit or KeyboardInterrupt escaping the command body is printed as 'Error: {e}' and converted into SystemExit(1). The real diagnostic is the underlying exception's message, which this handler re-displays. The finally block runs cleanup() (stopping the proxy, restoring env).

Source

Thrown at headroom/cli/wrap.py:2997

        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

    config_file, _ = _codex_config_paths()
    config_dir = config_file.parent

    # Use forward slashes in TOML paths (works on all platforms, avoids
    # backslash escaping issues on Windows)
    python_bin = sys.executable.replace("\\", "/")
    mcp_section = (

View on GitHub (pinned to 322425c43b)

Solutions

1. Read the exception text after 'Error:' — it identifies the actual failing operation; fix that root cause
2. Re-run with more logging (verbose flag / HEADROOM log level) and check log_dir()/proxy.log for a traceback
3. Validate the wrapped tool's config files (settings.json, config.toml) are valid JSON/TOML and writable
4. If the message is unhelpful, reproduce with `headroom wrap <tool> --verbose` or file an issue including the log

try:
    run_wrap_command()
except SystemExit as e:
    if e.code != 0:
        # 'Error: {e}' was already printed; capture logs for the real traceback
        log.debug("wrap failed, exit=%s, logs at %s", e.code, log_dir())
    raise

When it happens

Trigger: Any unexpected failure while preparing or launching the wrapped tool: proxy startup RuntimeErrors (port exhaustion, timeout, crashed child), config file read/write errors in the tool's settings, MCP injection failures, or filesystem permission errors — anything not deliberately handled earlier.

Common situations: Corrupt Claude/Codex settings JSON that Headroom cannot patch; permission errors writing to the tool's config dir; disk full; proxy startup failures bubbling up; edge-case bugs in argument handling for exotic flags.

Related errors

• No available port found in range {start_port}-{end_port - 1}
• Proxy exited with code {proc.returncode}: {tail}
• Proxy process exited unexpectedly.
• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.

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