influxdata/influxdb · critical · FormatError

payload CRC32 mismatch: expected

Error message

payload CRC32 mismatch: expected {expected:#010x}, computed {computed:#010x}

What it means

A persisted catalog file segment passed its header CRC32 check but the payload bytes failed verification: the CRC32 computed over the record payload ({computed:#010x}) does not match the checksum stored in the record header ({expected:#010x}). The catalog format validates every written record so that silent bit-rot or partial writes are detected on read instead of corrupting the in-memory catalog. This error means the file on disk is damaged or was written by incompatible code.

Solutions

1. Verify the storage medium and restore the catalog file from a known-good backup or snapshot.
2. Do not hand-edit catalog files; re-run restore from the object-store checkpoint referenced by the catalog.
3. If reproducible, check for concurrent writes to the same catalog file (two instances pointed at one data dir).
4. Report to influxdb3 maintainers with the file path and expected/computed CRCs if the file was written by a supported version.

Example fix

// before: manually editing the corrupt catalog file
// after: restore from backup via the catalog restore path
// catalog.apply(RestoreCatalog { checkpoint_path: known_good_snapshot })

// Before trusting a catalog file, verify integrity off-band
let meta = std::fs::metadata(catalog_path)?;
if meta.len() == 0 { return Err("catalog file empty/truncated"); }
// compare against checksum recorded at backup time
assert_eq!(sha256_file(catalog_path)?, expected_sha256, "catalog file corrupted");

match load_result {
    Err(e) if e.to_string().contains("CRC32 mismatch") => restore_from_backup(),
    Err(e) => return Err(e),
    Ok(c) => Ok(c),
}

When it happens

Trigger: Reading back a catalog snapshot or WAL segment whose payload bytes were corrupted (disk bit-rot, torn write during a crash, truncation mid-record), or a writer bug that computed the CRC over different bytes than it wrote.

Common situations: Running on failing storage, killing the process during a catalog write, copying catalog files while the database is live, or restoring a backup where files were transferred/mangled incorrectly.

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

• {0}
• invalid record length
• buffer too short: expected at least
• catalog format error
• corrupt load state

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

Appendix: source

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

    /// 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}"
    )]
    RecordExceedsFile {
        offset: u64,
        length: u32,
        file_size: u64,

View on GitHub (pinned to 06200ef96b)