risingwavelabs/risingwave · error · BackupError

storage_directory mismatch: {} {}

Error message

storage_directory mismatch: {} {}

What it means

Same validation family as the storage_url check: when not overwriting endpoints, the snapshot's storage_directory must equal `opts.hummock_storage_directory`. A mismatch means the snapshot's hummock data lives under a different object-storage directory than the target cluster expects.

Source

Thrown at src/meta/src/backup_restore/restore.rs:232

            || opts.overwrite_backup_storage_directory.is_none())
    {
        return Err(BackupError::Other(anyhow::anyhow!("overwrite_hummock_storage_endpoint, overwrite_backup_storage_url, overwrite_backup_storage_directory must be set simultaneously".to_owned())));
    }

    // Restore meta store.
    let target_snapshot = loader.load(target_id).await?;
    if !opts.overwrite_hummock_storage_endpoint {
        let storage_url = target_snapshot.metadata.storage_url()?;
        if storage_url != opts.hummock_storage_url {
            return Err(BackupError::Other(anyhow::anyhow!(
                "storage_url mismatch: {} {}",
                storage_url,
                opts.hummock_storage_url
            )));
        }
        let storage_directory = target_snapshot.metadata.storage_directory()?;
        if storage_directory != opts.hummock_storage_directory {
            return Err(BackupError::Other(anyhow::anyhow!(
                "storage_directory mismatch: {} {}",
                storage_directory,
                opts.hummock_storage_directory
            )));
        }
    }

    if opts.dry_run {
        tracing::info!("Complete dry run.");
        return Ok(());
    }
    let hummock_version = target_snapshot.metadata.hummock_version_ref().clone();
    writer.write(target_snapshot).await?;
    if opts.overwrite_hummock_storage_endpoint {
        writer
            .overwrite(
                &format!("hummock+{}", opts.hummock_storage_url),
                &opts.hummock_storage_directory,

View on GitHub (pinned to 6469eb736d)

Solutions

1. Set `--hummock-storage-directory` to match the snapshot's recorded storage_directory
2. Use the full overwrite path (overwrite_hummock_storage_endpoint + url + directory) when intentionally relocating the data
3. Confirm which backup/snapshot you restored from to learn its original directory

Example fix

// before
risectl meta restore --hummock-storage-directory path-b
// after
risectl meta restore --hummock-storage-directory path-a  # matches snapshot
# or add overwrite flags to relocate deliberately

if !opts.overwrite_hummock_storage_endpoint
    && target_snapshot.metadata.storage_directory()? != opts.hummock_storage_directory {
    return Err(anyhow!("storage_directory mismatch; align opts or use overwrite flags"));
}

When it happens

Trigger: Restore with overwrite_hummock_storage_endpoint=false while opts.hummock_storage_directory differs from target_snapshot.metadata.storage_directory().

Common situations: Backup taken with a custom hummock directory (e.g. `bucket/path-a`) restored into a cluster configured with another directory; environment migration without override flags.

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

• storage_url mismatch: {} {}
• overwrite_hummock_storage_endpoint, overwrite_backup_storage
• secret_store_private_key is not configured
• snapshot id {} not found
• not supported: write model V1 to meta store V2

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