herdrdev/herdr · error

downloaded remote asset checksum verification failed: {err}

Error message

downloaded remote asset checksum verification failed: {err}

What it means

After downloading the remote asset, herdr verifies its sha256 against the expected checksum from the release manifest. A mismatch or unreadable file causes verify_sha256 to fail and this error (preserving the verifier's error kind) is returned; the temp directory is removed.

Source

Thrown at src/remote/attach.rs:1449

    let asset_key = platform.asset_key();
    let asset = remote_release_asset(&asset_key)?;

    let dir = private_download_dir(&asset_key)?;
    let path = dir.join("herdr.tmp");
    let status = crate::noninteractive_process::curl_command()
        .args(["-sfL", "--max-time", "120", "-o"])
        .arg(&path)
        .arg(&asset.url)
        .status()
        .map_err(|err| io::Error::new(err.kind(), format!("download failed: {err}")))?;
    if !status.success() {
        let _ = fs::remove_dir_all(&dir);
        return Err(io::Error::other("download failed"));
    }
    if let Some(expected) = &asset.sha256 {
        if let Err(err) = crate::checksum::verify_sha256(&path, expected) {
            let _ = fs::remove_dir_all(&dir);
            return Err(io::Error::new(
                err.kind(),
                format!("downloaded remote asset checksum verification failed: {err}"),
            ));
        }
    }

    Ok(InstallSource::temporary(path, dir))
}

fn fetch_remote_manifest(url: &str) -> io::Result<Vec<u8>> {
    let output = crate::noninteractive_process::curl_command()
        .args([
            "-sfL",
            "--retry",
            "3",
            "--connect-timeout",
            "10",
            "--max-time",

View on GitHub (pinned to f457cff4f2)

Solutions

1. Retry the download (transient corruption is the most common cause)
2. Verify network path integrity: disable suspicious proxies or check MITM behavior
3. Clear any local manifest/asset cache and re-resolve the latest release
4. Manually compare sha256 of the URL against the published checksum to detect a re-published asset

Example fix

# manual verification
url=https://github.com/herdrdev/herdr/releases/latest/download/herdr-linux-x86_64
curl -sfL "$url" | sha256sum   # compare with manifest value

for attempt in 0..3 {
    match download_and_verify(asset) {
        Err(e) if e.to_string().contains("checksum") if attempt < 2 => continue,
        r => break r,
    }
}?

When it happens

Trigger: Corrupted or truncated download (proxy tampering, interrupted transfer), a release manifest whose sha256 does not match the actual asset, or the downloaded file becoming unreadable before hashing.

Common situations: Corporate proxies/MITM rewriting binaries, stale cached manifest pointing at re-published assets, disk-full truncation during download.

Related errors

• sha256 mismatch: expected {expected}, got {actual}
• expected sha256 must be 64 hexadecimal characters
• download failed: {err}
• remote bridge download failed: {err}
• api request line is too large

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