{"record":{"id":"307dc70cc3ee6dda","repo":"rustfs/rustfs","slug":"unsupported-sealed-credential-envelope-version-0","errorCode":null,"errorMessage":"unsupported sealed credential envelope version {0}","messagePattern":"unsupported sealed credential envelope version (.+?)","errorType":"exception","errorClass":"SealedCredentialError","httpStatus":null,"severity":"error","filePath":"crates/ecstore/src/bucket/sealed_credentials.rs","lineNumber":148,"sourceCode":"        if self.v == SEALED_CREDENTIAL_VERSION {\n            Ok(())\n        } else {\n            Err(SealedCredentialError::UnsupportedVersion(self.v))\n        }\n    }\n}\n\n/// Why a seal or unseal did not produce a usable value. Every variant is\n/// terminal for the record that carried it: a caller reports the remote as\n/// unusable, and never substitutes a default or empty credential.\n#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]\npub enum SealedCredentialError {\n    /// No sealer is installed: KMS is not configured, or the process has not\n    /// finished startup. Reading a sealed record is impossible here.\n    #[error(\"no credential sealer is installed\")]\n    NoSealer,\n    /// The stored envelope is from a newer (or otherwise unknown) format.\n    #[error(\"unsupported sealed credential envelope version {0}\")]\n    UnsupportedVersion(u8),\n    /// The stored bytes are not a well-formed envelope.\n    #[error(\"malformed sealed credential: {0}\")]\n    Malformed(String),\n    /// The sealer refused: wrong encryption context, missing key, revoked\n    /// access, or a failed authentication tag.\n    #[error(\"sealed credential could not be unsealed: {0}\")]\n    Kms(String),\n}\n\n/// The KMS-backed half, installed by the binary at startup.\n#[async_trait]\npub trait CredentialSealer: Send + Sync + 'static {\n    /// Wraps `plaintext` under the scope's encryption context.\n    async fn seal(&self, plaintext: &str, scope: &SealScope) -> Result<SealedCredential, SealedCredentialError>;\n\n    /// Unwraps a stored envelope. Must fail when the envelope was sealed\n    /// under a different scope.","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/rustfs/rustfs/blob/5dca076efed96e7b842de07c4c2111035ae7c7a2/crates/ecstore/src/bucket/sealed_credentials.rs#L130-L166","documentation":"SealedCredentialError::UnsupportedVersion(v) is thrown when a stored sealed-credential envelope carries a format version the reader does not know — typically an envelope written by a newer release. The library refuses to guess or parse unknown formats, so the record cannot be unsealed by this binary. It is a forward-compatibility guard against silently misreading binary data.","triggerScenarios":"Reading a sealed credential whose envelope header version byte exceeds the current implementation's maximum supported version; running an older binary against data produced by a newer RustFS version; mixed-version cluster where a node reads metadata written by upgraded peers.","commonSituations":"Rolling upgrades where an old node reads newly written records; restoring a backup from a newer version into an older deployment; downgraded binary after an upgrade.","solutions":["Upgrade the binary to a version that supports the envelope version in the message","If the rollback is intentional, reseal/rewrite the credentials with the old (supported) version using a binary that can read them","Keep cluster versions homogeneous or complete the rolling upgrade before reading records written by newer nodes","Check release notes for sealed-credential format changes before downgrading"],"exampleFix":"// before: reading with old binary\n// error: unsupported sealed credential envelope version 3\n// after: upgrade first\nrustfs-upgrade --to 1.x   # binary that supports envelope v3\n# then restart the service and re-read the record","handlingStrategy":"try-catch","validationCode":"null","typeGuard":"fn is_unsupported_version(e: &SealedCredentialError) -> Option<u8> {\n    if let SealedCredentialError::UnsupportedVersion(v) = e { Some(*v) } else { None }\n}","tryCatchPattern":"match store.load_sealed_credential(id).await {\n    Err(SealedCredentialError::UnsupportedVersion(v)) => {\n        // surface version for upgrade guidance; never attempt a guess-parse\n        return Err(UpgradeRequired { envelope_version: v });\n    }\n    r => r.map_err(Into::into),\n}","preventionTips":["Complete rolling upgrades before reading records on nodes still on the old version","Avoid downgrading binaries below the version that wrote your data","Pin and document envelope-format versions in release notes","Test mixed-version reads in staging upgrade drills"],"tags":["versioning","compatibility","kms","rust"],"backgroundTag":"unsupported-operation","analyzedSha":"5dca076efed96e7b842de07c4c2111035ae7c7a2","analyzedAt":"2026-09-06T05:54:05.891Z","contentChangedAt":"2026-09-06T05:54:05.891Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}