{"record":{"id":"9fe573248e0d6368","repo":"xai-org/grok-build","slug":"timeout-waiting-for-ipc-socket-to-be-created","errorCode":null,"errorMessage":"Timeout waiting for IPC socket to be created","messagePattern":"Timeout waiting for IPC socket to be created","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/codegen/xai-grok-shell/src/agent/app.rs","lineNumber":876,"sourceCode":"            client_count_for_server,\n            agent_busy_for_server,\n            agent_activity_for_server,\n            ready_rx,\n            relay_demand_tx,\n            shutdown_tx_for_server,\n            None,\n            control_state,\n        )\n        .await\n        {\n            warn!(error = ?e, \"Leader server error\");\n        }\n    });\n    let socket_ready_deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(5);\n    while !crate::leader::listener_is_ready(&socket_path) {\n        if tokio::time::Instant::now() >= socket_ready_deadline {\n            cancel.cancel();\n            return Err(anyhow::anyhow!(\n                \"Timeout waiting for IPC socket to be created\"\n            ));\n        }\n        tokio::time::sleep(std::time::Duration::from_millis(5)).await;\n    }\n    debug!(\"IPC socket created\");\n    let _lock = lock;\n    let ctx = &agent_config.grok_com_config;\n    suppress_otel();\n    let auth: Option<GrokAuth> = crate::auth::try_noninteractive_auth_no_mint(ctx).await;\n    let has_session = auth.is_some()\n        || agent_config\n            .create_auth_manager()\n            .read_disk_auth()\n            .is_some();\n    let session_pending =\n        crate::agent::otel_gate::is_session_pending(has_session, &agent_config.grok_com_config);\n    let policy_channel =","sourceCodeStart":858,"sourceCodeEnd":894,"githubUrl":"https://github.com/xai-org/grok-build/blob/bc7f02eddd3d84085849dc19ed216f11c23b0571/crates/codegen/xai-grok-shell/src/agent/app.rs#L858-L894","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Delete the stale socket file at socket_path (after confirming no live leader owns it) so bind() can succeed, then retry.","Check logs from the spawned server task for a bind error or panic; fix the underlying cause (permissions, path length).","Shorten the socket path (shallower directory) if it exceeds the Unix socket 108-byte limit.","Raise the 5-second socket_ready_deadline on slow/loaded machines where startup legitimately takes longer.","Re-run once — transient scheduling delays (post-suspend, CPU contention) often resolve on a fresh attempt."],"exampleFix":"// before: fixed 5s deadline\ncancel.cancel();\nreturn Err(anyhow::anyhow!(\"Timeout waiting for IPC socket to be created\"));\n\n// after: clean stale socket and allow a longer deadline\nif !crate::leader::listener_is_ready(&socket_path) {\n    let _ = std::fs::remove_file(&socket_path); // stale socket breaks bind\n}\nlet socket_ready_deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(30);","handlingStrategy":"try-catch","validationCode":"// before spawning: ensure the socket path is bindable\nlet dir = socket_path.parent().unwrap();\nstd::fs::create_dir_all(dir)?;\nif socket_path.exists() && !crate::leader::listener_is_ready(&socket_path) {\n    std::fs::remove_file(&socket_path).ok(); // stale socket\n}\nassert!(socket_path.to_string_lossy().len() < 108, \"unix socket path too long\");","typeGuard":"fn is_socket_create_timeout_err(e: &anyhow::Error) -> bool {\n    e.to_string() == \"Timeout waiting for IPC socket to be created\"\n}","tryCatchPattern":"if let Err(e) = run_agent_command(...).await {\n    if is_socket_create_timeout_err(&e) {\n        // inspect server-task logs for bind errors before blindly retrying\n        error!(\"IPC socket never appeared at {} — check listener logs\", socket_path.display());\n    }\n    return Err(e);\n}","preventionTips":["Remove stale socket files (after readiness probing) so the listener's bind() cannot fail on an existing path.","Keep the socket path well under the 108-byte sun_path limit — avoid deep cache directories.","Capture logs/panics from the spawned server task so a failed bind is visible instead of surfacing as a poll timeout.","On slow hosts or after resume-from-sleep, allow a startup deadline larger than 5 seconds."],"tags":["ipc","unix-socket","startup","timeout"],"backgroundTag":"ipc-socket-bind-timeout","analyzedSha":"bc7f02eddd3d84085849dc19ed216f11c23b0571","analyzedAt":"2026-08-31T04:59:42.031Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}