xai-org/grok-build · error

Timeout waiting for IPC socket to be created

Error message

Timeout waiting for IPC socket to be created

What it means

After the leader lock was acquired, run_leader spawns the server and polls crate::leader::listener_is_ready(&socket_path) every 5ms; if the IPC socket is not bound within 5 seconds (socket_ready_deadline), it cancels startup via cancel.cancel() and returns this error. It means the leader process won the lock but failed to create its IPC listener in time.

Solutions

1. Delete the stale socket file at socket_path (after confirming no live leader owns it) so bind() can succeed, then retry.
2. Check logs from the spawned server task for a bind error or panic; fix the underlying cause (permissions, path length).
3. Shorten the socket path (shallower directory) if it exceeds the Unix socket 108-byte limit.
4. Raise the 5-second socket_ready_deadline on slow/loaded machines where startup legitimately takes longer.
5. Re-run once — transient scheduling delays (post-suspend, CPU contention) often resolve on a fresh attempt.

Example fix

// before: fixed 5s deadline
cancel.cancel();
return Err(anyhow::anyhow!("Timeout waiting for IPC socket to be created"));

// after: clean stale socket and allow a longer deadline
if !crate::leader::listener_is_ready(&socket_path) {
    let _ = std::fs::remove_file(&socket_path); // stale socket breaks bind
}
let socket_ready_deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(30);

// before spawning: ensure the socket path is bindable
let dir = socket_path.parent().unwrap();
std::fs::create_dir_all(dir)?;
if socket_path.exists() && !crate::leader::listener_is_ready(&socket_path) {
    std::fs::remove_file(&socket_path).ok(); // stale socket
}
assert!(socket_path.to_string_lossy().len() < 108, "unix socket path too long");

fn is_socket_create_timeout_err(e: &anyhow::Error) -> bool {
    e.to_string() == "Timeout waiting for IPC socket to be created"
}

if let Err(e) = run_agent_command(...).await {
    if is_socket_create_timeout_err(&e) {
        // inspect server-task logs for bind errors before blindly retrying
        error!("IPC socket never appeared at {} — check listener logs", socket_path.display());
    }
    return Err(e);
}

When it happens

Trigger: The spawned listener task in run_leader fails to bind or is delayed, so `while !listener_is_ready(&socket_path)` never becomes true before `Instant::now() + 5s`; bind errors on the socket path (address in use, permission, overlong Unix socket path >108 bytes), or a heavily loaded/suspended host stalling the spawn.

Common situations: Leftover socket file at the path causing bind() to fail; socket path inside a deeply nested directory exceeding sun_path limits; system under heavy load or coming back from suspend so startup exceeds 5s; listener task panics before binding (missing deps, unwrap on bad config).

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• connect timed out
• Another leader already holds the lock at
• Timed out acquiring leader lock at
• unix socket path too long
• -32603

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/9fe573248e0d6368. Report an issue: GitHub.

Appendix: source

Thrown at crates/codegen/xai-grok-shell/src/agent/app.rs:876

            client_count_for_server,
            agent_busy_for_server,
            agent_activity_for_server,
            ready_rx,
            relay_demand_tx,
            shutdown_tx_for_server,
            None,
            control_state,
        )
        .await
        {
            warn!(error = ?e, "Leader server error");
        }
    });
    let socket_ready_deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(5);
    while !crate::leader::listener_is_ready(&socket_path) {
        if tokio::time::Instant::now() >= socket_ready_deadline {
            cancel.cancel();
            return Err(anyhow::anyhow!(
                "Timeout waiting for IPC socket to be created"
            ));
        }
        tokio::time::sleep(std::time::Duration::from_millis(5)).await;
    }
    debug!("IPC socket created");
    let _lock = lock;
    let ctx = &agent_config.grok_com_config;
    suppress_otel();
    let auth: Option<GrokAuth> = crate::auth::try_noninteractive_auth_no_mint(ctx).await;
    let has_session = auth.is_some()
        || agent_config
            .create_auth_manager()
            .read_disk_auth()
            .is_some();
    let session_pending =
        crate::agent::otel_gate::is_session_pending(has_session, &agent_config.grok_com_config);
    let policy_channel =

View on GitHub (pinned to bc7f02eddd)