influxdata/influxdb · critical · FormatError

header CRC32 mismatch: expected

Error message

header CRC32 mismatch: expected {expected:#010x}, actual {actual:#010x}

What it means

`FormatError::HeaderCrc32Mismatch` is returned when the CRC32 checksum stored in a catalog file's header does not match the checksum computed over the header bytes read from disk. This detects header corruption — the file content has changed since it was written.

Solutions

Restore the catalog file from a verified backup
Check the storage device/filesystem for errors (SMART, fsck) before writing new data
Do not hand-edit catalog files; re-generate or repair via official tooling
Compare against a known-good copy to confirm the extent of corruption

Defensive patterns

Strategy: try-catch

Try / catch

match result {
    Err(FormatError::HeaderCrc32Mismatch { expected, actual }) => {
        log::error!("catalog header corrupt: stored {expected:#010x}, computed {actual:#010x}");
        // restore from verified backup
    }
    r => r?,
}

Prevention

Run periodic filesystem/device health checks (SMART, fsck)
Verify checksums on backups before trusting restores
Never hand-edit catalog files
Maintain off-host backups of catalog data

When it happens

Trigger: Reading a catalog file whose header CRC field (expected) differs from the computed CRC over the actual header bytes.

Common situations: Bit rot or disk corruption; files modified/truncated after writing; bad restores or manual edits; failing storage hardware.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

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 },

    /// Invalid record length.
    #[error("invalid record length: {length}")]
    InvalidRecordLength { length: u32 },

    /// Record data exceeds remaining file.
    #[error(
        "record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}"
    )]

View on GitHub (pinned to 06200ef96b)