risingwavelabs/risingwave · critical · BackupError

Checksum mismatch: expected {expected}, found: {found}

Error message

Checksum mismatch: expected {expected}, found: {found}

What it means

`BackupError::ChecksumMismatch` signals that data read from a backup did not match its stored checksum: the computed checksum (`found`) differs from the recorded one (`expected`). This guards against silent corruption of backup artifacts in storage.

Source

Thrown at src/storage/backup/src/error.rs:52

    #[error("StateStorage error: {0}")]
    StateStorage(
        #[backtrace]
        #[source]
        BoxedError,
    ),
    #[error("Encoding error: {0}")]
    Encoding(
        #[backtrace]
        #[source]
        BoxedError,
    ),
    #[error("Decoding error: {0}")]
    Decoding(
        #[backtrace]
        #[source]
        BoxedError,
    ),
    #[error("Checksum mismatch: expected {expected}, found: {found}")]
    ChecksumMismatch { expected: u64, found: u64 },
    #[error("Meta storage is not empty before being restored")]
    NonemptyMetaStorage,
    #[error(transparent)]
    Other(
        #[from]
        #[backtrace]
        anyhow::Error,
    ),
}

impl From<std::io::Error> for BackupError {
    fn from(err: std::io::Error) -> Self {
        if err.kind() == std::io::ErrorKind::UnexpectedEof {
            Self::Decoding(anyhow::anyhow!("unexpected EOF while decoding meta snapshot").into())
        } else {
            Self::BackupStorage(err.into())
        }

View on GitHub (pinned to 6469eb736d)

Solutions

1. Treat the backup artifact as corrupt; do not restore from it.
2. Re-download/copy the backup from the original location and verify again.
3. Re-create the backup from the source cluster if the artifact is unavailable elsewhere.

// Verify checksums of all backup artifacts before restore
fn verify(expected: u64, actual: u64) -> Result<(), String> {
    (expected == actual).then(|| ()).ok_or_else(|| format!("checksum mismatch: expected {expected}, found {actual}"))
}

match restore().await {
    Err(e @ BackupError::ChecksumMismatch { .. }) => {
        tracing::error!(error = ?e, "backup corrupted — abort restore, do NOT proceed");
        return Err(anyhow::anyhow!("backup artifact corrupt; obtain a fresh backup"));
    }
    other => other?,
}

When it happens

Trigger: During restore or verification, a backup file/manifest's computed checksum differs from the value recorded when the backup was written, e.g. `ChecksumMismatch { expected: 123, found: 456 }`.

Common situations: Bit-rot or corruption in the object store; truncated/partial uploads or downloads; manual modification of backup files; copying artifacts with a lossy tool.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• metadata JSON payload length exceeds usize
• concurrent backup job is not supported: existent job {}
• too many existent meta snapshots, expect at most {}
• inconsistent hummock version: expected {}, actual {}
• snapshot id {} not found

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/e2a3602def46199f. Report an issue: GitHub.