risingwavelabs/risingwave · error · BackupError

BackupStorage error: {0}

Error message

BackupStorage error: {0}

What it means

`BackupError::BackupStorage` wraps an underlying error from the backup storage backend (the object store/blob storage used to hold backup data) in `risingwave_storage::backup`. It preserves the original error as `#[source]` with a backtrace, indicating the failure occurred while talking to the backup storage layer.

Source

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

// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use risingwave_common::error::BoxedError;
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}")]

View on GitHub (pinned to 6469eb736d)

Solutions

1. Inspect the wrapped `#[source]`/backtrace to find the root cause (auth, network, permissions).
2. Verify backup storage configuration: bucket/endpoint/region and credentials.
3. Test access to the backup storage from the node (e.g. aws s3 ls) and retry the operation.

// Check backup storage reachability before running backup
let ok = tokio::fs::metadata("/dev/null").is_ok(); // plus storage-specific: s3 head_bucket
// e.g. client.head_bucket().await.is_ok()

match run_backup().await {
    Err(e) if matches!(e, BackupError::BackupStorage(_) | BackupError::BackupStorage(..)) => {
        tracing::error!(error = ?e, "backup storage failure");
        // inspect e.source() for root cause, then retry with backoff
    }
    other => other?,
}

When it happens

Trigger: Any backup/restore operation (`meta_backup`, `storage backup`) whose read/write to the remote backup storage fails: failed upload of a backup manifest, failed download of an SST or metadata file, or storage client initialization errors.

Common situations: Misconfigured S3 credentials/bucket for backup storage; network outage or throttling (S3 503); expired credentials; wrong endpoint; bucket deleted or permissions revoked.

Related errors

• MetaStorage error: {0}
• (dataset guard acquisition error)
• failed to read Lance transaction history
• concurrent backup job is not supported: existent job {}
• too many existent meta snapshots, expect at most {}

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