risingwavelabs/risingwave · error · BackupError

invalid state_store from metadata snapshot: {}

Error message

invalid state_store from metadata snapshot: {}

What it means

MetaSnapshotV2::storage_url strips the "hummock+" prefix from the snapshot's state_store value; if the value lacks that prefix it throws "invalid state_store from metadata snapshot: {}" with the offending value. The stored state store URL must be a Hummock-compatible URL for restore to rebuild storage config.

Source

Thrown at src/storage/backup/src/meta_snapshot_v2.rs:218

    fn hummock_version(self) -> HummockVersion {
        self.hummock_version
    }

    fn storage_url(&self) -> BackupResult<String> {
        let storage_url_from_snapshot =
            Itertools::exactly_one(self.system_parameters.iter().filter_map(|m| {
                if m.name == "state_store" {
                    return Some(m.value.clone());
                }
                None
            }))
            .map_err(|_| BackupError::Other(anyhow!("expect state_store")))?;
        storage_url_from_snapshot
            .strip_prefix("hummock+")
            .map(|s| s.to_owned())
            .ok_or_else(|| {
                BackupError::Other(anyhow!(
                    "invalid state_store from metadata snapshot: {}",
                    storage_url_from_snapshot
                ))
            })
    }

    fn storage_directory(&self) -> BackupResult<String> {
        Itertools::exactly_one(self.system_parameters.iter().filter_map(|m| {
            if m.name == "data_directory" {
                return Some(m.value.clone());
            }
            None
        }))
        .map_err(|_| BackupError::Other(anyhow!("expect data_directory")))
    }

    fn table_change_log_object_ids(&self) -> HashSet<HummockRawObjectId> {
        self.hummock_table_change_logs

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Check the persisted state_store value in the snapshot (it is included in the error) and confirm what the cluster was configured with at backup time.
  2. Recreate the backup from a cluster whose state_store is a valid hummock URL (e.g. hummock+s3://bucket).
  3. Patch the snapshot's system_parameter entry to a valid hummock+ URL if you know the intended store, then retry restore.
  4. Validate state_store config (must match ^hummock\+.+) before starting the cluster that will be backed up.

Example fix

// before: cluster configured with a bare URL
-- state_store = "s3://bucket"
// after: persist a hummock-prefixed URL
-- state_store = "hummock+s3://bucket"
Defensive patterns

Strategy: validation

Validate before calling

let v = snapshot.system_parameters.iter().find(|m| m.name == "state_store")
    .map(|m| m.value.clone()).unwrap_or_default();
if !v.starts_with("hummock+") {
    return Err(anyhow!("state_store must start with hummock+, got: {}", v));
}

Type guard

fn is_hummock_url(v: &str) -> bool { v.starts_with("hummock+") }

Try / catch

match snapshot.storage_url() {
    Ok(url) => url,
    Err(e) if e.to_string().contains("invalid state_store") => {
        return Err(anyhow!("snapshot from non-hummock cluster; cannot auto-restore"));
    }
    Err(e) => return Err(e.into()),
}

Prevention

When it happens

Trigger: storage_url() finding a state_store parameter whose value does not start with "hummock+" — e.g. the cluster was configured with a non-hummock or malformed state_store string at backup time.

Common situations: A cluster run with an experimental/modified state store URL; a typo in state_store config persisted into system parameters before the backup; snapshots from environments using URL schemes the restore code doesn't recognize.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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