influxdata/influxdb · critical · FormatError

unsupported format version

Error message

unsupported format version: {version}

What it means

`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.

Solutions

1. Upgrade influxdb3 to a version that supports the file's format version
2. Restore the catalog from a backup compatible with the current version
3. Do not downgrade below the version that wrote the catalog; export/migrate data instead

let version = read_format_version(&file)?;
if version > SUPPORTED_VERSION {
    return Err(format!("catalog format v{version} unsupported; upgrade influxdb3"));
}

match result {
    Err(FormatError::UnsupportedVersion { version }) => {
        log::error!("unsupported catalog format v{version}");
        // upgrade influxdb3 or restore compatible backup
    }
    r => r?,
}

When it happens

Trigger: Opening a catalog file whose header version field is higher (or unrecognized) relative to the reader's supported version.

Common situations: Downgrading influxdb3 after a newer version rewrote the catalog; reading files produced by a fork or newer release; mixed-version clusters.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• unknown record id without UPGRADE_SAFE flag
• buffer too short: expected at least
• failed to serialize record id
• invalid magic bytes: expected
• {0}

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

Appendix: source

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

    /// Create flags with UPGRADE_SAFE set.
    pub const fn upgrade_safe() -> Self {
        Self(Self::UPGRADE_SAFE)
    }
}

/// Errors that can occur when working with the binary format.
#[derive(Debug, Clone, thiserror::Error)]
pub enum FormatError {
    /// A decoded record failed to apply to the catalog.
    #[error(transparent)]
    Apply(#[from] apply::ApplyError),

    /// Invalid magic bytes at start of file.
    #[error("invalid magic bytes: expected {expected:?}, got {actual:?}")]
    InvalidMagic { expected: [u8; 4], actual: [u8; 4] },

    /// Unsupported format version.
    #[error("unsupported format version: {version}")]
    UnsupportedVersion { version: u32 },

    /// Buffer too short for required data.
    #[error("buffer too short: expected at least {expected} bytes, got {actual}")]
    BufferTooShort { expected: usize, actual: usize },

    /// Header CRC32 checksum mismatch.
    #[error("header CRC32 mismatch: expected {expected:#010x}, actual {actual:#010x}")]
    HeaderCrc32Mismatch { expected: u32, actual: u32 },

    /// Payload CRC32 checksum mismatch.
    #[error("payload CRC32 mismatch: expected {expected:#010x}, computed {computed:#010x}")]
    Crc32Mismatch { expected: u32, computed: u32 },

    /// Unknown record type without UPGRADE_SAFE flag — hard error.
    #[error("unknown record id {record_id} without UPGRADE_SAFE flag")]
    UnknownNonUpgradeSafeRecord { record_id: u16 },

View on GitHub (pinned to 06200ef96b)