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

downloaded file too small to be a valid binary

Error message

downloaded file too small to be a valid binary

What it means

check_binary_arch opens the staged file and reads up to 4096 bytes of its header to detect the machine type (ELF/PE/Mach-O). Fewer than 20 bytes were read, which is below the minimum needed to parse any executable format, so the file is judged not to be a valid binary at all.

Source

Thrown at src/commands/update.rs:748

}

async fn check_binary_arch(path: &Path) -> Result<()> {
    use tokio::io::AsyncReadExt;

    // Read only the header — enough to cover a PE file's DOS stub and reach the
    // COFF machine field pointed to by `e_lfanew` (well under 4 KiB in practice)
    // — instead of pulling the whole multi-megabyte binary into memory.
    let mut header = Vec::new();
    tokio::fs::File::open(path)
        .await
        .context("failed to open binary to read header")?
        .take(4096)
        .read_to_end(&mut header)
        .await
        .context("failed to read binary header")?;

    if header.len() < 20 {
        bail!("downloaded file too small to be a valid binary");
    }

    let binary_arch = detect_arch_from_header(&header);
    let host_arch = host_architecture();

    if let (Some(bin), Some(host)) = (binary_arch, host_arch)
        && bin != host
    {
        bail!(
            "architecture mismatch: downloaded binary is {bin} but this host is {host} — \
             the release asset may be mispackaged"
        );
    }

    Ok(())
}

fn detect_arch_from_header(header: &[u8]) -> Option<&'static str> {

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Re-run `zeroclaw update` to redo download and unpack from scratch.
2. Check free space on the volume holding the temp/staging directory.
3. Inspect the staged file size if you have a custom harness feeding the pipeline; anything under 20 bytes is not an executable.
4. If it reproduces on a stock install, report it with OS and disk details.

match run_update().await {
    Err(e) if e.to_string().contains("too small to be a valid binary") => {
        // empty staged file: re-run the full download+unpack
    }
    other => other,
}

When it happens

Trigger: `zeroclaw update` when the staged binary path exists but is empty or nearly empty: extraction wrote a zero-length file (interrupted unpack, disk full), or a placeholder/empty body survived the earlier size checks in a hand-crafted flow.

Common situations: Interrupted or crashed unpack step; temp filesystem full during extraction; testing harnesses that stage fake files into the update pipeline.

Related errors

• downloaded binary too small ({} bytes), likely corrupt
• downloaded binary --version check failed
• downloaded binary does not appear to be zeroclaw
• architecture mismatch: downloaded binary is {bin} but this h
• channel does not support room creation

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