shutdown was requested, but the old remote herdr server on {

Error message

shutdown was requested, but the old remote herdr server on {target} is still responding after {} seconds

What it means

After requesting shutdown of an old remote herdr server, herdr polls remote_server_status until REMOTE_SERVER_SHUTDOWN_CONFIRM_TIMEOUT elapses. If the server is still responding past the deadline, this TimedOut error is raised because the stale server never confirmed shutdown.

Source

Thrown at src/remote/attach.rs:1391

        return Err(command_failed("remote server stop failed", &output));
    }

    wait_for_remote_server_shutdown(ssh, remote_herdr)?;
    eprintln!(
        "stopped the remote herdr server on {}; it will restart when the remote client bridge attaches.",
        ssh.target()
    );
    Ok(())
}

fn wait_for_remote_server_shutdown(ssh: &RemoteSsh, remote_herdr: &RemoteHerdr) -> io::Result<()> {
    let deadline = Instant::now() + REMOTE_SERVER_SHUTDOWN_CONFIRM_TIMEOUT;
    loop {
        if remote_server_status(ssh, remote_herdr)? == RemoteServerStatus::NotRunning {
            return Ok(());
        }
        if Instant::now() >= deadline {
            return Err(io::Error::new(
                io::ErrorKind::TimedOut,
                format!(
                    "shutdown was requested, but the old remote herdr server on {target} is still responding after {} seconds",
                    REMOTE_SERVER_SHUTDOWN_CONFIRM_TIMEOUT.as_secs(),
                    target = ssh.target()
                ),
            ));
        }
        thread::sleep(REMOTE_SERVER_SHUTDOWN_POLL_INTERVAL);
    }
}

fn version_label(version: Option<&str>) -> &str {
    version.unwrap_or("unknown")
}

fn warn_if_remote_bin_not_on_path(ssh: &RemoteSsh) -> io::Result<()> {
    let output = ssh.user_shell_output("command -v herdr")?;

View on GitHub (pinned to f457cff4f2)

Solutions

SSH into the remote host and kill the stale herdr server process (pkill -f herdr), then retry attach
Check remote system load and disk/socket issues delaying shutdown
Upgrade the remote herdr binary so shutdown handling is current
Retry after manually confirming the remote socket is gone (herdr server status / socket path)

Defensive patterns

Strategy: retry

Try / catch

match wait_remote_shutdown(ssh, target) {
    Err(e) if e.kind() == std::io::ErrorKind::TimedOut => {
        manually_stop_remote_server().await?;
        wait_remote_shutdown(ssh, target).await
    }
    r => r,
}

Prevention

Monitor remote server health and stop stale servers proactively
Keep remote herdr updated so shutdown handling is reliable
On timeout, fall back to killing the remote process and retry once

When it happens

Trigger: Issuing a remote server stop (typically during protocol-mismatch restart) where the remote process ignores or delays the shutdown request, e.g. busy event loop, stuck child panes, or network latency between the SSH control commands and the server.

Common situations: Remote host under heavy load, remote herdr version that does not handle shutdown cleanly, SSH multiplexing delays, or a zombie server process holding the socket.

Related errors

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