{"record":{"id":"9aa69e83f9373693","repo":"openai/codex","slug":"mcp-http-headers-helper-failed-to-start-error","errorCode":null,"errorMessage":"MCP HTTP headers helper failed to start: {error}","messagePattern":"MCP HTTP headers helper failed to start: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"codex-rs/rmcp-client/src/http_headers.rs","lineNumber":304,"sourceCode":"    #[cfg(unix)]\n    process.process_group(0);\n    process\n        .stdin(Stdio::null())\n        .stdout(Stdio::piped())\n        .stderr(Stdio::null())\n        .current_dir(cwd)\n        // Match local MCP subprocess policy; arbitrary ambient variables are not inherited.\n        .env_clear()\n        .envs(create_env_for_mcp_server(/*extra_env*/ None, &[])?)\n        .kill_on_drop(true);\n\n    #[cfg(windows)]\n    let (child, job) = {\n        let job = codex_utils_pty::JobObject::create_without_breakaway()\n            .map_err(|error| anyhow!(\"MCP HTTP headers helper containment failed: {error}\"))?;\n        let child = job\n            .spawn_contained(&mut process)\n            .map_err(|error| anyhow!(\"MCP HTTP headers helper failed to start: {error}\"))?;\n        (child, job)\n    };\n    #[cfg(not(windows))]\n    let child = process\n        .spawn()\n        .map_err(|error| anyhow!(\"MCP HTTP headers helper failed to start: {error}\"))?;\n    let mut process = HelperProcess {\n        #[cfg(unix)]\n        process_group_id: child\n            .id()\n            .ok_or_else(|| anyhow!(\"MCP HTTP headers helper process id was unavailable\"))?,\n        child,\n        #[cfg(windows)]\n        job,\n    };\n    let output = tokio::time::timeout(HELPER_TIMEOUT, async {\n        let stdout = process\n            .child","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/openai/codex/blob/339751715c64496cb86246bfb3935f40e309dd3d/codex-rs/rmcp-client/src/http_headers.rs#L286-L322","documentation":"Windows path of run_helper(): the Job Object was created, but spawn_contained() could not start %COMSPEC% /Q /D /C \"<command\" — the child never launched. The helper runs with a cleared environment (env_clear()) plus only the minimal MCP-server env, so PATH resolution, the configured cwd, and COMSPEC itself are the usual suspects. This is a spawn failure, distinct from the helper running and exiting non-zero.","triggerScenarios":"An httpHeadersHelper command that cmd.exe cannot execute: bare executable name not resolvable on the minimal PATH, missing configured cwd directory, malformed quoting, or a COMSPEC pointing at an unavailable shell.","commonSituations":"Helpers referencing tools by bare name (my-helper.exe) that happen to be on the interactive PATH but not the cleared env's; cwd configured to a deleted/renamed folder; locked-down machines where cmd.exe is blocked by policy.","solutions":["Use an absolute path to the helper executable in the command string","Verify the configured cwd exists and is readable","Test locally: cmd /Q /D /C \"<command>\" from that cwd with a stripped environment (env -i equivalent)","Check COMSPEC is set to an accessible shell on the host"],"exampleFix":"# before\nhttpHeadersHelper = \"my-auth-helper --json\"\n\n# after\nhttpHeadersHelper = \"C:\\\\Tools\\\\my-auth-helper.exe --json\"","handlingStrategy":"validation","validationCode":":: Test on Windows from the configured cwd with a minimal environment before wiring in the helper\ncd /d \"%MCP_CWD%\" && cmd /Q /D /C \"%HTTP_HEADERS_HELPER%\" >NUL\nif errorlevel 1 (echo helper failed to start/exit nonzero)","typeGuard":"fn is_helper_spawn_failure(error: &anyhow::Error) -> bool {\n    error.to_string().contains(\"headers helper failed to start\")\n}","tryCatchPattern":null,"preventionTips":["Use absolute paths for the helper executable","Verify the configured cwd exists before connecting","Keep COMSPEC pointing at a working cmd.exe","Remember the helper env is cleared: only minimal MCP env vars exist"],"tags":["rust","mcp","windows","process-spawn","headers-helper","cmd","env-clear"],"backgroundTag":"process-spawn-failed","analyzedSha":"339751715c64496cb86246bfb3935f40e309dd3d","analyzedAt":"2026-08-25T05:35:09.876Z","schemaVersion":2},"datasetVersion":"2026-08-25T06:17:31.827Z"}