risingwavelabs/risingwave · error · HummockError

Read backup error: {0}

Error message

Read backup error: {0}

What it means

HummockError::ReadBackupError (src/storage/src/hummock/error.rs:75-76, constructor read_backup_error at error.rs:177-179) wraps failures while reading a cluster backup (the snapshot of meta state that includes hummock manifest data). It is thrown when backup files cannot be read, decoded, or found in the object store during backup restore.

Source

Thrown at src/storage/src/hummock/error.rs:75

    )]
    CommittedEpochMismatch {
        table_id: TableId,
        committed_epoch: u64,
        read_epoch: u64,
    },
    #[error("Barrier read is unavailable for now. Likely the cluster is recovering")]
    ReadCurrentEpoch,
    #[error("CompactionExecutor error: {0}")]
    CompactionExecutor(String),
    #[error("FileCache error: {0}")]
    FileCache(String),
    #[error("SstObjectIdTracker error: {0}")]
    SstObjectIdTrackerError(String),
    #[error("CompactionGroup error: {0}")]
    CompactionGroupError(String),
    #[error("SstableUpload error: {0}")]
    SstableUploadError(String),
    #[error("Read backup error: {0}")]
    ReadBackupError(String),
    #[error("Foyer error: {0}")]
    FoyerError(#[from] foyer::Error),
    #[error("Other error: {0}")]
    Other(String),
}

impl HummockError {
    pub fn invalid_format_version(v: u32) -> HummockError {
        HummockErrorInner::InvalidFormatVersion(v).into()
    }

    pub fn invalid_block() -> HummockError {
        HummockErrorInner::InvalidBlock.into()
    }

    pub fn encode_error(error: impl ToString) -> HummockError {
        HummockErrorInner::EncodeError(error.to_string()).into()

View on GitHub (pinned to 6469eb736d)

Solutions

1. Verify the backup ID and object store path are correct for the backup you intend to restore
2. Check that backup objects still exist in the bucket and were not deleted by lifecycle/cleanup policies
3. Retry the restore; if the network or credentials are at fault it will succeed once fixed
4. If the backup is incomplete or corrupt, fall back to another backup; do not attempt to repair partial backups

Example fix

// before: restoring from an expired/deleted backup id
risectl restore --meta-store-snapshot <stale_backup_id>
// after: list available backups and pick a valid, complete one
risectl backup list
risectl restore --meta-store-snapshot <valid_backup_id>

// before restore, list backups and confirm the target is complete
let backups = risectl_list_backups().await?;
let chosen = backups
    .iter()
    .find(|b| b.id == target_backup_id && b.status == "Success")
    .expect("backup must exist with Success status");

fn is_read_backup_err(e: &HummockError) -> bool {
    e.to_report_string().starts_with("Read backup error:")
}

match restore_from_backup(target_backup_id).await {
    Err(e) if is_read_backup_err(&e) => {
        error!(error = %e.report(), "backup unreadable; do not continue restore");
        // pick another complete backup instead of retrying a corrupt one
        Err(e)
    }
    other => other,
}

When it happens

Trigger: Running `risectl` or admin commands that restore from a backup and the backup manifest/data file cannot be read from the object store; decoding a backup manifest fails; the backup being referenced was deleted or is incomplete.

Common situations: Wrong backup ID given to restore tooling; object store bucket contents pruned/cleaned before restore; network/permission failures reaching the backup files; partially written backups from an aborted backup job.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Storage error: {0}
• StorageError {error}
• referenced objects not found in object store: {:?}
• ObjectStore failed with IO error: {0}
• SstableUpload error: {0}

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