risingwavelabs/risingwave · error · BackupError

StateStorage error

Error message

StateStorage error: {0}

What it means

`BackupError::StateStorage` wraps an underlying error from the state storage (Hummock) layer during backup operations. Reading SST/object metadata or state data needed to build a backup failed; the original error is preserved as source with backtrace.

Solutions

1. Read the wrapped source error for the root cause (I/O, auth, missing object).
2. Ensure the object store backing Hummock is healthy and objects are not being GC'd concurrently.
3. Retry the backup once storage access is restored; check Hummock GC settings if objects vanish.

// Ensure object store is reachable and required SSTs exist before backup
for sst in required_ssts {
    assert!(object_store.head(sst).await.is_ok(), "missing {sst:?}");
}

match create_backup().await {
    Err(e @ BackupError::StateStorage(_)) => {
        // transient object-store errors dominate; retry with backoff
        retry_with_backoff(create_backup).await
    }
    other => other?,
}

When it happens

Trigger: Creating a storage backup: listing/reading SST files from Hummock/object store, fetching versioned data or manifest entries; failures from the state store client are wrapped in this variant.

Common situations: Object store credentials expired mid-backup; SST files garbage-collected before backup completed; network partition to S3/minio; version/manifest inconsistencies in Hummock.

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

• inconsistent hummock version: expected
• BackupStorage error
• checkpoint checksum mismatch: expected
• checkpoint missing required field `version`
• Checksum mismatch: expected

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

Appendix: source

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

use thiserror::Error;

pub type BackupResult<T> = Result<T, BackupError>;

#[derive(Error, Debug)]
pub enum BackupError {
    #[error("BackupStorage error: {0}")]
    BackupStorage(
        #[backtrace]
        #[source]
        BoxedError,
    ),
    #[error("MetaStorage error: {0}")]
    MetaStorage(
        #[backtrace]
        #[source]
        BoxedError,
    ),
    #[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}")]

View on GitHub (pinned to 6469eb736d)