{"record":{"id":"41867c5dfe339734","repo":"influxdata/influxdb","slug":"unsupported-format-version-version","errorCode":null,"errorMessage":"unsupported format version: {version}","messagePattern":"unsupported format version: (.+?)","errorType":"error_code","errorClass":"FormatError","httpStatus":null,"severity":"critical","filePath":"influxdb3_catalog/src/format/mod.rs","lineNumber":175,"sourceCode":"    /// Create flags with UPGRADE_SAFE set.\n    pub const fn upgrade_safe() -> Self {\n        Self(Self::UPGRADE_SAFE)\n    }\n}\n\n/// Errors that can occur when working with the binary format.\n#[derive(Debug, Clone, thiserror::Error)]\npub enum FormatError {\n    /// A decoded record failed to apply to the catalog.\n    #[error(transparent)]\n    Apply(#[from] apply::ApplyError),\n\n    /// Invalid magic bytes at start of file.\n    #[error(\"invalid magic bytes: expected {expected:?}, got {actual:?}\")]\n    InvalidMagic { expected: [u8; 4], actual: [u8; 4] },\n\n    /// Unsupported format version.\n    #[error(\"unsupported format version: {version}\")]\n    UnsupportedVersion { version: u32 },\n\n    /// Buffer too short for required data.\n    #[error(\"buffer too short: expected at least {expected} bytes, got {actual}\")]\n    BufferTooShort { expected: usize, actual: usize },\n\n    /// Header CRC32 checksum mismatch.\n    #[error(\"header CRC32 mismatch: expected {expected:#010x}, actual {actual:#010x}\")]\n    HeaderCrc32Mismatch { expected: u32, actual: u32 },\n\n    /// Payload CRC32 checksum mismatch.\n    #[error(\"payload CRC32 mismatch: expected {expected:#010x}, computed {computed:#010x}\")]\n    Crc32Mismatch { expected: u32, computed: u32 },\n\n    /// Unknown record type without UPGRADE_SAFE flag — hard error.\n    #[error(\"unknown record id {record_id} without UPGRADE_SAFE flag\")]\n    UnknownNonUpgradeSafeRecord { record_id: u16 },\n","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/format/mod.rs#L157-L193","documentation":"`FormatError::UnsupportedVersion` is returned when a catalog format file declares a format version the current library does not support. This guards against reading files written by incompatible (usually newer) versions of the catalog format.","triggerScenarios":"Opening a catalog file whose header version field is higher (or unrecognized) relative to the reader's supported version.","commonSituations":"Downgrading influxdb3 after a newer version rewrote the catalog; reading files produced by a fork or newer release; mixed-version clusters.","solutions":["Upgrade influxdb3 to a version that supports the file's format version","Restore the catalog from a backup compatible with the current version","Do not downgrade below the version that wrote the catalog; export/migrate data instead"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"let version = read_format_version(&file)?;\nif version > SUPPORTED_VERSION {\n    return Err(format!(\"catalog format v{version} unsupported; upgrade influxdb3\"));\n}","typeGuard":null,"tryCatchPattern":"match result {\n    Err(FormatError::UnsupportedVersion { version }) => {\n        log::error!(\"unsupported catalog format v{version}\");\n        // upgrade influxdb3 or restore compatible backup\n    }\n    r => r?,\n}","preventionTips":["Never downgrade below the version that wrote the catalog","Pin cluster versions during rolling upgrades","Check release notes for catalog format bumps before version changes"],"tags":["catalog","versioning","compatibility","file-format"],"backgroundTag":"incompatible-source-type","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}