influxdata/influxdb · error · FormatError

failed to load restore source

Error message

failed to load restore source: {0}

What it means

A RestoreCatalog record referenced backup snapshot/log files, but loading them from the object store failed; the underlying error message is embedded ({0}). The restore cannot proceed because the source of the backup state is unreadable. This wraps store/network/decode failures behind a single restore-specific error.

Solutions

1. Read the wrapped source error to identify whether it is auth, network, or missing-object, and fix that first.
2. Verify the checkpoint/log files referenced by the RestoreCatalog record still exist in the object store.
3. Check object-store credentials and bucket/endpoint configuration.
4. Retry the restore if the failure was transient (network).

// Precheck: confirm the restore source objects exist and are readable before applying
for obj in restore_source_paths {
    if !store.object_exists(&obj).await? {
        return Err(format!("restore source missing: {}", obj));
    }
}

match preload_restore(...) {
    Err(e) if is_transient(&e) => backoff_retry(|| preload_restore(...), 3),
    Err(e) => return Err(e),
    ok => ok,
}

When it happens

Trigger: Applying a RestoreCatalog record whose checkpoint or log files are missing, unreadable, or fail to decode; transient object-store (S3/GCS/Azure/HTTP) errors during restore preload.

Common situations: Deleted or expired backup snapshots; wrong bucket/prefix configuration; object-store credentials revoked; network outage mid-restore.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• object store error
• restore checkpoint not found at
• Failed to delete table index snapshot from object store
• Failed to list table indices from object store
• Failed to load table index from object store

AI-assisted analysis of influxdata/influxdb@06200ef96b (2026-09-19). Data as JSON: /api/errors/2157037d7d226200. Report an issue: GitHub.

Appendix: source

Thrown at influxdb3_catalog/src/format/mod.rs:227

    /// nonzero).
    #[error("invalid header: {reason}")]
    InvalidHeader { reason: &'static str },

    /// A `RestoreCatalog` record was encountered during sync apply with an
    /// empty preload. Callers on a persistence path must first load the
    /// backup state off-lock via `preload_restore_for_records` /
    /// `preload_restore_for_file` and pass the resulting `RestorePreload`
    /// into the apply call.
    #[error(
        "RestoreCatalog record encountered without object-store access \
         (sync apply path): the catalog cannot reload backup state from \
         here — use the async apply path"
    )]
    RestoreRequiresStore,

    /// Loading the backup snapshot/log files referenced by a `RestoreCatalog`
    /// record failed.
    #[error("failed to load restore source: {0}")]
    RestoreLoadFailed(String),

    /// The checkpoint or log path in a `RestoreCatalog` record could not be
    /// parsed as an object-store path.
    #[error("invalid restore path: {0}")]
    InvalidRestorePath(String),

    /// The backup snapshot referenced by a `RestoreCatalog` record was not
    /// found at the recorded checkpoint path.
    #[error("restore checkpoint not found at {checkpoint_path}")]
    RestoreCheckpointMissing { checkpoint_path: String },

    /// A decoded record could not be serialized to a value for inspection.
    #[error("failed to serialize record id {record_id} to value: {reason}")]
    RecordToValue { record_id: u16, reason: String },
}

#[cfg(test)]

View on GitHub (pinned to 06200ef96b)