openai/codex · error

runner handshake task failed: {err}

Error message

runner handshake task failed: {err}

What it means

Error "runner handshake task failed: {err}" thrown in openai/codex.

Source

Thrown at codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated.rs:107

            )
        },
    )
}

async fn spawn_runner_transport_task(
    sandbox_creds: SandboxCreds,
    request: RunnerTransportRequest,
) -> Result<RunnerTransport> {
    tokio::task::spawn_blocking(move || -> Result<_> {
        spawn_runner_transport_with_retry(
            sandbox_creds,
            &request,
            spawn_runner_transport,
            refresh_logon_sandbox_creds,
        )
    })
    .await
    .map_err(|err| anyhow::anyhow!("runner handshake task failed: {err}"))?
}

#[allow(clippy::too_many_arguments)]
pub(crate) async fn spawn_windows_sandbox_session_elevated_for_permission_profile(
    permission_profile: &PermissionProfile,
    workspace_roots: &[AbsolutePathBuf],
    codex_home: &Path,
    command: Vec<String>,
    cwd: &Path,
    mut env_map: HashMap<String, String>,
    proxy_enforced: bool,
    network_proxy_restricting_sid: Option<String>,
    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
    timeout_ms: Option<u64>,
    read_roots_override: Option<&[PathBuf]>,
    read_roots_include_platform_defaults: bool,
    write_roots_override: Option<&[PathBuf]>,
    deny_read_paths_override: &[AbsolutePathBuf],

View on GitHub (pinned to 339751715c)

Solutions

  1. Check the inner error for the handshake failure cause, verify the elevated runner binary matches the client version, and restart the runner process.

When it happens

Trigger: Thrown at codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated.rs:107 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/7c4dace9587fc854. Report an issue: GitHub.