rustfs/rustfs · error · BackupError

unknown backup manifest format version {found} (this build s

Error message

unknown backup manifest format version {found} (this build supports version {supported})

What it means

BackupError version guard meaning the manifest declares a format version this build does not understand (found > supported). There is deliberately no best-effort read of unknown versions; restore aborts fail-closed. The values are the bundle's declared version and this build's maximum supported version, telling the operator to upgrade RustFS/KMS before restoring this bundle.

Source

Thrown at crates/kms/src/backup/error.rs:39

/// Every variant is a fail-closed condition: a restore surface observing any
/// of them must abort before touching target state. Messages carry only
/// identifiers (backup ids, KEK ids, artifact kinds and paths) — never key
/// material, bundle plaintext, or credentials.
#[derive(Error, Debug, Clone, PartialEq, Eq)]
pub enum BackupError {
    /// Manifest or bundle content fails structural, schema, or integrity
    /// validation (unknown fields, duplicate fields, digest mismatch,
    /// contradictory responsibility declarations, ...).
    #[error("backup bundle corrupted: {reason}")]
    Corrupted { reason: String },

    /// Input ended before a complete manifest could be decoded.
    #[error("backup manifest truncated: {reason}")]
    Truncated { reason: String },

    /// Manifest declares a format version this build does not understand.
    /// Unknown versions are always rejected; there is no best-effort read.
    #[error("unknown backup manifest format version {found} (this build supports version {supported})")]
    UnknownVersion { found: u32, supported: u32 },

    /// Bundle is protected by a different backup KEK than the one supplied.
    #[error(
        "backup bundle requires KEK '{required_kek_id}' version {required_kek_version}; \
         supplied KEK '{supplied_kek_id}' version {supplied_kek_version} cannot open it"
    )]
    WrongKek {
        required_kek_id: String,
        required_kek_version: u32,
        supplied_kek_id: String,
        supplied_kek_version: u32,
    },

    /// A bundled key record declares a format version this build does not
    /// understand.
    #[error("bundled key record '{key_id}' declares unsupported format version {version}; this build cannot restore it")]
    UnsupportedFormatVersion { key_id: String, version: String },

View on GitHub (pinned to 35af688cd9)

Solutions

1. Upgrade to a build supporting the manifest version
2. Restore with the software generation that wrote the backup

When it happens

Trigger: Thrown at crates/kms/src/backup/error.rs:39 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of rustfs/rustfs@35af688cd9 (2026-08-20). Data as JSON: /api/errors/f8682b3842948a75. Report an issue: GitHub.