influxdata/influxdb · critical · FormatError

invalid record length

Error message

invalid record length: {length}

What it means

A record read from the catalog log declared an implausible length field ({length}). The reader rejects lengths that cannot form a valid record (e.g. zero or beyond the framing limits), concluding the framing is broken rather than trusting the value. This almost always indicates byte-level corruption or a misaligned read offset.

Solutions

1. Restore the catalog files from a verified backup or the object-store checkpoint.
2. Check that all catalog segment files were copied completely and unmodified (compare checksums of the copied files against source).
3. Stop any process concurrently writing to the catalog directory during backup/restore.

// Sanity-check copied files before pointing InfluxDB at them
for f in catalog_files {
    let copied = fs::metadata(dest.join(f))?.len();
    let src = fs::metadata(src.join(f))?.len();
    if copied != src { return Err(format!("{} size mismatch (partial copy?)", f)); }
}

if let Err(e) = catalog.replay() {
    if e.to_string().contains("invalid record length") {
        eprintln!("catalog framing corrupted; restore from checkpoint");
    }
}

When it happens

Trigger: Reading a catalog log whose length prefix was overwritten/corrupted, or reading at a wrong offset (e.g. after skipping records incorrectly), or a truncated file where a partial length was read.

Common situations: Disk corruption, manual file surgery on catalog files, restoring a partially-copied snapshot, tooling that concatenated catalog segments incorrectly.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {0}
• payload CRC32 mismatch: expected
• 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/d1c9ed90af5bacdf. Report an issue: GitHub.

Appendix: source

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

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

    /// File header is internally inconsistent (e.g. a reserved field is
    /// nonzero).
    #[error("invalid header: {reason}")]
    InvalidHeader { reason: &'static str },

    /// A `RestoreCatalog` record was encountered during sync apply with an

View on GitHub (pinned to 06200ef96b)