herdrdev/herdr · error

failed to inspect {REMOTE_BINARY_ENV_VAR} path {}: {err}

Error message

failed to inspect {REMOTE_BINARY_ENV_VAR} path {}: {err}

What it means

This error is thrown when the code cannot stat the path pointed to by the HERDR_REMOTE_BINARY environment variable (REMOTE_BINARY_ENV_VAR). The fs::metadata call failed and the underlying OS error kind is preserved. It means the configured remote binary path is inaccessible, does not exist, or has permission problems.

Source

Thrown at src/remote/attach.rs:905

fn remote_binary_exists(ssh: &RemoteSsh, remote_herdr: &RemoteHerdr) -> io::Result<bool> {
    let command = format!("test -x {}", remote_herdr.shell_path);
    Ok(ssh.sh_output(&command)?.status.success())
}

fn remote_binary_override_path() -> io::Result<Option<PathBuf>> {
    let Some(value) = std::env::var_os(REMOTE_BINARY_ENV_VAR) else {
        return Ok(None);
    };
    if value.is_empty() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!("{REMOTE_BINARY_ENV_VAR} must not be empty"),
        ));
    }

    let path = PathBuf::from(value);
    let metadata = fs::metadata(&path).map_err(|err| {
        io::Error::new(
            err.kind(),
            format!(
                "failed to inspect {REMOTE_BINARY_ENV_VAR} path {}: {err}",
                path.display()
            ),
        )
    })?;
    if !metadata.is_file() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!(
                "{REMOTE_BINARY_ENV_VAR} path is not a file: {}",
                path.display()
            ),
        ));
    }

    Ok(Some(path))

View on GitHub (pinned to f457cff4f2)

Solutions

1. Verify the path exists and is readable: ls -l "$HERDR_REMOTE_BINARY"
2. Point HERDR_REMOTE_BINARY at an absolute path to the local herdr binary that actually exists
3. Check directory traversal permissions on every component of the path
4. Unset the variable to let herdr auto-detect or download the remote binary

Example fix

# before
export HERDR_REMOTE_BINARY=/opt/herdr/bin/herdr  # does not exist
# after
export HERDR_REMOTE_BINARY=/usr/local/bin/herdr  # verify with: ls -l /usr/local/bin/herdr

use std::path::Path;

fn remote_binary_ok(p: &str) -> bool {
    let path = Path::new(p);
    !p.is_empty()
        && std::fs::metadata(path)
            .map(|m| m.is_file())
            .unwrap_or(false)
}

match run_attach() {
    Err(e) if e.kind() == std::io::ErrorKind::NotFound => eprintln!("HERDR_REMOTE_BINARY path missing: check the path"),
    r => r,
}

When it happens

Trigger: Setting HERDR_REMOTE_BINARY to a path that does not exist on the local machine, a path inside a directory without execute/search permission, a broken symlink, or a path on an unmounted filesystem, then invoking remote attach.

Common situations: Typo in the env var value, pointing at a path that only exists on the remote host rather than locally, stale path after the binary was moved or deleted, or a symlink whose target is missing.

Related errors

• {REMOTE_BINARY_ENV_VAR} path is not a file: {}
• failed to create unique scrollback temp file
• failed to {operation} managed plugin checkout at {}; close a
• failed to create private herdr ssh config directory
• {REMOTE_BINARY_ENV_VAR} must not be empty

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