herdrdev/herdr · warning

server did not become ready within {}s (socket: {}). The bac

Error message

server did not become ready within {}s (socket: {}). The background server may still be starting; try `herdr` again, or check {}

What it means

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.

Source

Thrown at src/server/autodetect.rs:265

pub fn wait_for_server_socket(socket_path: &Path, timeout: Duration) -> io::Result<()> {
    let deadline = std::time::Instant::now() + timeout;

    while std::time::Instant::now() < deadline {
        #[cfg(windows)]
        if client_protocol_accepts_hello(socket_path)? {
            info!(path = %socket_path.display(), "server client protocol ready");
            return Ok(());
        }

        #[cfg(not(windows))]
        if is_server_listening_at(socket_path) {
            info!(path = %socket_path.display(), "server socket ready");
            return Ok(());
        }
        std::thread::sleep(SOCKET_POLL_INTERVAL);
    }

    Err(io::Error::new(
        io::ErrorKind::TimedOut,
        format!(
            "server did not become ready within {}s (socket: {}). The background server may still be starting; try `herdr` again, or check {}",
            timeout.as_secs(),
            socket_path.display(),
            crate::session::data_dir().join("herdr-server.log").display()
        ),
    ))
}

// ---------------------------------------------------------------------------
// Auto-detect launch
// ---------------------------------------------------------------------------

/// Performs auto-detect launch: check for server, spawn if needed, then
/// attach as a thin client.
///
/// This is the entry point called from `main.rs` when the user runs `herdr`

View on GitHub (pinned to f457cff4f2)

Solutions

1. Simply run `herdr` again as the message suggests (covers slow starts)
2. Check the herdr-server.log path shown in the message for startup errors
3. Verify socket path overrides (HERDR_SOCKET_PATH) match between client and server
4. If it recurs, increase the readiness timeout or investigate why the server binds slowly

if crate::server::autodetect::wait_for_server_socket(&socket, Duration::from_secs(1)).is_ok() { /* proceed */ }

Err(e) if e.kind() == io::ErrorKind::TimedOut => { sleep; retry once; then surface log path to user }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• timed out reading api request
• timed out waiting for app response after {} ms
• timed out reading stream frame header
• timed out reading stream frame body
• Windows notification setup timed out

AI-assisted analysis of herdrdev/herdr@f457cff4f2 (2026-08-28). Data as JSON: /api/errors/6037e44d199fe248. Report an issue: GitHub.