influxdata/influxdb · critical · FormatError

record data exceeds file bounds: offset

Error message

record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}

What it means

A record header at offset {offset} declares a payload of {length} bytes, but the file is only {file_size} bytes, so the record body extends past the end of the file. The reader refuses to read past EOF, indicating the file was truncated after the header was written (crash mid-write) or the length field is corrupt.

Solutions

Restore the file from the latest complete checkpoint/snapshot in object storage.
Verify file sizes against the source when copying (e.g. rsync --checksum) and re-copy if truncated.
Ensure InfluxDB is fully stopped before copying catalog files at the filesystem level.
Check disk health and free space on the node.

Example fix

// before: cp -r /var/lib/influxdb3/* /backup  (while running)
// after: stop influxdb3, then copy
// systemctl stop influxdb3 && cp -r /var/lib/influxdb3 /backup

Defensive patterns

Strategy: validation

Validate before calling

// Verify expected file size before open (compare to checkpoint manifest)
let sz = fs::metadata(&path)?.len();
if sz < expected_min_size_from_manifest {
    return Err(format!("{} truncated: {} < {} bytes", path.display(), sz, expected_min_size_from_manifest));
}

Try / catch

match catalog.open() {
    Err(e) if e.to_string().contains("exceeds file bounds") => restore_latest_checkpoint()?,
    other => other,
}

Prevention

Shut down the DB cleanly before backups; avoid copying live appended files
Ensure adequate disk space so writes are never cut short
Use object-store snapshots/checkpoints instead of raw file copies

When it happens

Trigger: Opening a catalog snapshot/WAL that was truncated by a crash or interrupted copy; a corrupted length field; manually copying a file while it was still being appended.

Common situations: Power loss during catalog flush; rsync/cp of a live data directory; running out of disk causing partial writes; incomplete restore from object store.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

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

    /// 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
    /// empty preload. Callers on a persistence path must first load the
    /// backup state off-lock via `preload_restore_for_records` /
    /// `preload_restore_for_file` and pass the resulting `RestorePreload`
    /// into the apply call.

View on GitHub (pinned to 06200ef96b)