spacedriveapp/spacedrive · error · anyhow::Error

Checksum verification failed

Error message

Checksum verification failed

What it means

FastCopyStrategy (core/src/ops/files/copy/strategy.rs:234) verifies integrity after std::fs::copy: it hashes source and destination with calculate_file_checksum and compares. A mismatch aborts the operation with this bare error. The comment states the intent: detect CoW (copy-on-write) bugs and hardware errors such as bit flips and bad sectors — i.e., the bytes on disk at the destination do not equal the source.

Source

Thrown at core/src/ops/files/copy/strategy.rs:234

		}

		if let Some(parent) = dest_path.parent() {
			fs::create_dir_all(parent).await?;
		}

		let bytes_copied = tokio::task::spawn_blocking({
			let source_path = source_path.to_path_buf();
			let dest_path = dest_path.to_path_buf();
			move || -> Result<u64, std::io::Error> { std::fs::copy(&source_path, &dest_path) }
		})
		.await??;

		// Post-copy verification detects CoW bugs and hardware errors (bit flips, bad sectors).
		if verify_checksum {
			let source_checksum = calculate_file_checksum(source_path).await?;
			let dest_checksum = calculate_file_checksum(dest_path).await?;
			if source_checksum != dest_checksum {
				return Err(anyhow::anyhow!("Checksum verification failed"));
			}
		}

		// Signal file completion to aggregator
		if let Some(callback) = progress_callback {
			callback(bytes_copied, u64::MAX);
		}

		ctx.log(format!(
			"Fast copy: {} -> {} ({} bytes)",
			source_path.display(),
			dest_path.display(),
			bytes_copied
		));

		Ok(bytes_copied)
	}
}

View on GitHub (pinned to 6dfeccf211)

Solutions

1. Retry the copy once — transient read/write errors are the most common cause and a re-run usually succeeds.
2. Ensure the source is quiescent: stop indexers/editors/sync tools writing to it, or copy from a snapshot.
3. Check hardware: run `smartctl -a` on the destination disk, test RAM (memtest), try a different cable/port for external drives.
4. If it reproduces deterministically on one file pair, read both files back byte-by-byte (cmp) to confirm on-disk divergence, then file a bug — deterministic mismatch on healthy hardware indicates a CoW/clone-path defect.
5. Only as a last resort copy with verify_checksum=false (you lose integrity detection).

Example fix

// before: single attempt, aborts job on transient storage hiccup
let n = FastCopyStrategy.execute(ctx, src, dst, true, cb).await?;

// after: one bounded retry for transient checksum mismatch
let n = match FastCopyStrategy.execute(ctx, src, dst, true, cb).await {
    Ok(n) => n,
    Err(e) if e.to_string().contains("Checksum verification failed") => {
        ctx.log(format!("checksum mismatch, retrying once: {e}"));
        FastCopyStrategy.execute(ctx, src, dst, true, cb).await?
    }
    Err(e) => return Err(e),
};

// before enabling verification, confirm the source is not actively changing
async fn source_is_stable(path: &std::path::Path) -> bool {
    let a = tokio::fs::metadata(path).await.map(|m| (m.len(), m.modified().ok())).ok()?;
    tokio::time::sleep(std::time::Duration::from_millis(250)).await;
    let b = tokio::fs::metadata(path).await.map(|m| (m.len(), m.modified().ok())).ok()?;
    Some(a == b)
}

// bounded retry with hardware escalation after repeated mismatches
const MAX: usize = 2;
for attempt in 1..=MAX {
    match FastCopyStrategy.execute(ctx, source, dest, true, cb).await {
        Ok(n) => break Ok(n),
        Err(e) if e.to_string().contains("Checksum verification failed") && attempt < MAX => {
            tracing::warn!(attempt, "checksum mismatch, retrying");
            continue;
        }
        Err(e) if e.to_string().contains("Checksum verification failed") => {
            break Err(anyhow::anyhow!("repeated checksum mismatch; inspect destination disk health (smartctl)"));
        }
        Err(e) => break Err(e),
    }
}

When it happens

Trigger: Calling copy with verify_checksum=true where (a) the source file is modified concurrently while being copied (indexer, editor, sync client), (b) the destination disk has bad sectors or flaky USB/NAS storage, (c) a filesystem CoW/clone bug copies wrong extents, or (d) memory errors corrupt data in flight.

Common situations: Copying files that are still being written (recent downloads, active logs); failing HDD/SD-card/USB drive; exotic filesystems (btrfs/zfs reflink corner cases, network filesystems); overclocked/unstable RAM.

Related errors

• Failed to generate content hash: {}
• Checksum verification failed: source={}, dest={}
• Source path is not local
• Destination path is not local
• Destination must have a device slug for cross-device transfe

AI-assisted analysis of spacedriveapp/spacedrive@6dfeccf211 (2026-08-16). Data as JSON: /api/errors/e2ce582c4deb334c. Report an issue: GitHub.