What causes "downloaded binary too small ({} bytes), likely corrupt" in zeroclaw-labs/zeroclaw?

Re-run `zeroclaw update`; transient truncation is the most common cause and a retry fixes it.

zeroclaw-labs/zeroclaw · error · anyhow::Error

downloaded binary too small ({} bytes), likely corrupt

Error message

downloaded binary too small ({} bytes), likely corrupt

What it means

validate_binary is a sanity gate the updater runs on the staged binary before installing it. Any staged file smaller than 1,000,000 bytes is rejected as 'likely corrupt' because real zeroclaw release binaries are multi-megabyte Rust builds. This catches truncated downloads and non-binary bodies before they can replace a working install.

Source

Thrown at src/commands/update.rs:703

            // file_type() does *not* follow symlinks, so a symlink shows up as
            // is_symlink() — we drop it rather than dereferencing it.
            let Ok(ft) = entry.file_type() else { continue };
            let path = entry.path();
            if ft.is_dir() {
                stack.push(path);
            } else if ft.is_file() {
                out.push(path);
            }
            // Symlinks and any other special files are silently skipped.
        }
    }
    out
}

async fn validate_binary(path: &Path) -> Result<()> {
    let meta = tokio::fs::metadata(path).await?;
    if meta.len() < 1_000_000 {
        bail!(
            "downloaded binary too small ({} bytes), likely corrupt",
            meta.len()
        );
    }

    // Check binary architecture before attempting execution so we can give
    // a clear diagnostic instead of the opaque "Exec format error (os error 8)".
    check_binary_arch(path).await?;

    // Quick check: try running --version
    let output = tokio::process::Command::new(path)
        .arg("--version")
        .output()
        .await
        .context("cannot execute downloaded binary")?;

    if !output.status.success() {
        bail!("downloaded binary --version check failed");

View on GitHub (pinned to 88bb9c8533)

Solutions

Re-run `zeroclaw update`; transient truncation is the most common cause and a retry fixes it.
Compare the asset's published size on the release page with what lands on disk if the error repeats.
Check free space in the temp/staging directory and clear it if full.
If the published asset itself is tiny (mispackaged release), report it and pin the previous version.

Defensive patterns

Strategy: retry

Try / catch

let mut attempt = 0;
loop {
    attempt += 1;
    match run_update().await {
        Err(e) if e.to_string().contains("too small") && attempt < 3 => continue, // re-download
        other => break other,
    }
}

Prevention

Wrap unattended self-updates in a retry with backoff; truncated transfers are transient.
Monitor temp/staging disk space so extraction never writes short files.
Alert when the downloaded asset size differs sharply from the published size.

When it happens

Trigger: `zeroclaw update` after a download or unpack step that produced a short file: connection cut mid-transfer, a proxy/CDN error page saved as the asset body, a rate-limit response body, or disk-full during staging.

Common situations: Flaky networks, corporate proxies or MITM filters returning small HTML error bodies, GitHub rate limiting, low disk space in the temp/staging directory.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/0f7b17f45ae902d6. Report an issue: GitHub.