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.

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)

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
• unix socket path too long: {}
• Another leader already holds the lock at {}
• Timed out acquiring leader lock at {}
• wait failed: {body}

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