herdrdev/herdr · error

{REMOTE_BINARY_ENV_VAR} path is not a file: {}

Error message

{REMOTE_BINARY_ENV_VAR} path is not a file: {}

What it means

After successfully statting the HERDR_REMOTE_BINARY path, herdr checks that it is a regular file. This error means the metadata shows the path is a directory, socket, device, or other non-file entity, so it cannot be executed as the remote binary.

Source

Thrown at src/remote/attach.rs:914

    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))
}

fn install_source_description(platform: &RemotePlatform, override_binary: Option<&Path>) -> String {
    install_source_description_for(
        platform,
        override_binary,
        local_binary_can_seed_remote(platform),
    )
}

View on GitHub (pinned to f457cff4f2)

Solutions

1. Set HERDR_REMOTE_BINARY to the full path of the herdr executable file, not its directory
2. Confirm with: file "$HERDR_REMOTE_BINARY" showing a regular executable
3. Unset the variable to fall back to automatic resolution

Example fix

# before
export HERDR_REMOTE_BINARY=/usr/local/bin
# after
export HERDR_REMOTE_BINARY=/usr/local/bin/herdr

let p = std::env::var("HERDR_REMOTE_BINARY")?;
let meta = std::fs::metadata(&p)?;
if !meta.is_file() {
    eprintln!("{p} is not a regular file; fix HERDR_REMOTE_BINARY");
}

When it happens

Trigger: Setting HERDR_REMOTE_BINARY to a directory (e.g. the bin directory instead of the binary itself), a FIFO, or a device node like /dev/null.

Common situations: User points the env var at the install directory ("/usr/local/bin" instead of "/usr/local/bin/herdr") or at a symlinked wrapper directory.

Related errors

• failed to inspect {REMOTE_BINARY_ENV_VAR} path {}: {err}
• expected sha256 must be 64 hexadecimal characters
• {flag} must be an integer between 1 and {}
• {flag} must be greater than 0
• {REMOTE_BINARY_ENV_VAR} must not be empty

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