{"record":{"id":"6037e44d199fe248","repo":"herdrdev/herdr","slug":"server-did-not-become-ready-within-s-socket","errorCode":null,"errorMessage":"server did not become ready within {}s (socket: {}). The background server may still be starting; try `herdr` again, or check {}","messagePattern":"server did not become ready within (.+?)s \\(socket: (.+?)\\)\\. The background server may still be starting; try `herdr` again, or check (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/server/autodetect.rs","lineNumber":265,"sourceCode":"pub fn wait_for_server_socket(socket_path: &Path, timeout: Duration) -> io::Result<()> {\n    let deadline = std::time::Instant::now() + timeout;\n\n    while std::time::Instant::now() < deadline {\n        #[cfg(windows)]\n        if client_protocol_accepts_hello(socket_path)? {\n            info!(path = %socket_path.display(), \"server client protocol ready\");\n            return Ok(());\n        }\n\n        #[cfg(not(windows))]\n        if is_server_listening_at(socket_path) {\n            info!(path = %socket_path.display(), \"server socket ready\");\n            return Ok(());\n        }\n        std::thread::sleep(SOCKET_POLL_INTERVAL);\n    }\n\n    Err(io::Error::new(\n        io::ErrorKind::TimedOut,\n        format!(\n            \"server did not become ready within {}s (socket: {}). The background server may still be starting; try `herdr` again, or check {}\",\n            timeout.as_secs(),\n            socket_path.display(),\n            crate::session::data_dir().join(\"herdr-server.log\").display()\n        ),\n    ))\n}\n\n// ---------------------------------------------------------------------------\n// Auto-detect launch\n// ---------------------------------------------------------------------------\n\n/// Performs auto-detect launch: check for server, spawn if needed, then\n/// attach as a thin client.\n///\n/// This is the entry point called from `main.rs` when the user runs `herdr`","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/herdrdev/herdr/blob/f457cff4f2648eee85d176f8a41861241d4e8428/src/server/autodetect.rs#L247-L283","documentation":"auto_detect_launch polled for the server's unix socket to appear for the configured timeout and gave up. The error is TimedOut and tells the user the server may still be starting, where the socket is, and where the server log lives. It does not necessarily mean the server failed; it may just be slow.","triggerScenarios":"Calling wait_for_server_socket when the server daemon has not bound its API socket within the timeout: slow disk, cold start, server crash during init, or socket path mismatch via overrides.","commonSituations":"First launch on slow machines, server crashing on startup (check herdr-server.log), socket path overrides pointing somewhere the server isn't, heavy system load delaying bind.","solutions":["Simply run `herdr` again as the message suggests (covers slow starts)","Check the herdr-server.log path shown in the message for startup errors","Verify socket path overrides (HERDR_SOCKET_PATH) match between client and server","If it recurs, increase the readiness timeout or investigate why the server binds slowly"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if crate::server::autodetect::wait_for_server_socket(&socket, Duration::from_secs(1)).is_ok() { /* proceed */ }","typeGuard":null,"tryCatchPattern":"Err(e) if e.kind() == io::ErrorKind::TimedOut => { sleep; retry once; then surface log path to user }","preventionTips":["Retry `herdr` once before assuming failure","Watch herdr-server.log for real startup errors","Align socket path overrides between invocations"],"tags":["timeout","server-startup","socket-polling","autodetect"],"backgroundTag":"service-startup-timeout","analyzedSha":"f457cff4f2648eee85d176f8a41861241d4e8428","analyzedAt":"2026-08-28T15:41:09.197Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}