herdrdev/herdr · error

failed to connect to remote Herdr client socket {}: {err}

Error message

failed to connect to remote Herdr client socket {}: {err}

What it means

The remote client bridge failed to connect a UnixStream to the local herdr client socket after ensuring the remote server is running. The original error kind is preserved, with the failing socket path embedded in the message. It typically indicates the server's client socket is absent, not yet listening, or permission-restricted.

Source

Thrown at src/remote/host_unix.rs:13

//! Unix remote-host side of the SSH stdio bridge.

use std::io;
use std::os::unix::net::UnixStream;
use std::thread;
use std::time::Duration;

pub(crate) fn run_remote_client_bridge() -> io::Result<()> {
    ensure_remote_server_running()?;

    let socket_path = crate::server::socket_paths::client_socket_path();
    let stream = UnixStream::connect(&socket_path).map_err(|err| {
        io::Error::new(
            err.kind(),
            format!(
                "failed to connect to remote Herdr client socket {}: {err}",
                socket_path.display()
            ),
        )
    })?;

    let mut stdout = io::stdout().lock();
    let mut socket_to_stdout = stream.try_clone()?;
    let mut stdin_to_socket = stream;

    let _upload = thread::spawn(move || {
        let mut stdin = io::stdin();
        let _ = copy_flush(&mut stdin, &mut stdin_to_socket);
        let _ = stdin_to_socket.shutdown(std::net::Shutdown::Write);
    });

View on GitHub (pinned to f457cff4f2)

Solutions

1. Retry the bridge after a short delay to cover the socket-bind race
2. Verify the client socket path exists: ls -l on the path shown in the message
3. Inspect herdr-server.log for server-side bind failures
4. Unset stale HERDR_CLIENT_SOCKET_PATH overrides or point them at the live server

let path = crate::server::socket_paths::client_socket_path();
if !path.exists() { /* wait or start server first */ }

Err(e) if matches!(e.kind(), io::ErrorKind::ConnectionRefused | io::ErrorKind::NotFound) => retry with backoff

When it happens

Trigger: Calling run_remote_client_bridge() when client_socket_path() does not exist, the server has not bound the client socket yet, another process holds it, or filesystem permissions deny access.

Common situations: Server started but client socket not yet created (race), HERDR_CLIENT_SOCKET_PATH override pointing to a stale path, server crashed after startup check, socket directory removed by tmpfiles cleanup.

Related errors

• failed to create unique scrollback temp file
• failed to {operation} managed plugin checkout at {}; close a
• failed to create private herdr ssh config directory
• login shell {shell:?} is not executable
• failed to create private herdr ssh config directory

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