What causes "Failed to verify download for model {}: {}. Please retry." in cjpais/Handy?

cjpais/Handy · error · anyhow::Error

Failed to verify download for model {}: {}. Please retry.

Error message

Failed to verify download for model {}: {}. Please retry.

What it means

The SHA256 computation itself failed with an I/O error before producing a digest; the inner error text is embedded in the message. The downloader treats an unverifiable file as untrustworthy: it deletes the file and asks for a retry. This is a local read failure, not a content mismatch.

Source

Thrown at src-tauri/src/managers/model/download.rs:78

        match Self::compute_sha256(path) {
            Ok(actual) if actual == expected => {
                info!("SHA256 verified for model {}", model_id);
                Ok(())
            }
            Ok(actual) => {
                warn!(
                    "SHA256 mismatch for model {}: expected {}, got {}",
                    model_id, expected, actual
                );
                let _ = fs::remove_file(path);
                Err(anyhow::anyhow!(
                    "Download verification failed for model {}: file is corrupt. Please retry.",
                    model_id
                ))
            }
            Err(e) => {
                let _ = fs::remove_file(path);
                Err(anyhow::anyhow!(
                    "Failed to verify download for model {}: {}. Please retry.",
                    model_id,
                    e
                ))
            }
        }
    }

    /// Computes the SHA256 hex digest of a file, reading in 64KB chunks to handle large models.
    fn compute_sha256(path: &Path) -> Result<String> {
        let mut file = File::open(path)?;
        let mut hasher = Sha256::new();
        let mut buffer = [0u8; 65536];
        loop {
            let n = file.read(&mut buffer)?;
            if n == 0 {
                break;
            }

View on GitHub (pinned to 98a4d80cce)

Solutions

Retry the download
Exclude the app's models directory from antivirus/backup real-time scanning
Free disk space and run a filesystem check
Ensure the process still has read permission on models_dir and the partial file

Defensive patterns

Strategy: retry

Try / catch

match downloader.download_http_resumable(...).await {
    Ok(outcome) => Ok(outcome),
    Err(e) if e.to_string().contains("Failed to verify download") => {
        // local I/O failure during hashing (AV lock, disk issue): retry after a pause
        tokio::time::sleep(Duration::from_secs(2)).await;
        downloader.download_http_resumable(...).await
    }
    Err(e) => Err(e),
}

Prevention

Exclude the models directory from real-time antivirus and backup scanning
Keep free disk headroom several times the model size for write-then-verify
Check dmesg/system logs for disk errors when this recurs

When it happens

Trigger: The downloaded file was locked or removed by another process (antivirus, backup agent, indexer) while hashing; disk full or failing sectors; permissions on models_dir changed between write and verify.

Common situations: Windows Defender or other AV scanning large GGUF downloads and locking them; aggressive backup software; models dir on an ejected or dying external drive.

Related errors

AI-assisted analysis of cjpais/Handy@98a4d80cce (2026-08-16). Data as JSON: /api/errors/33182402c4f1cc78. Report an issue: GitHub.