{"record":{"id":"233e5af131eededf","repo":"influxdata/influxdb","slug":"record-data-exceeds-file-bounds-offset-offset-length-length","errorCode":null,"errorMessage":"record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}","messagePattern":"record data exceeds file bounds: offset (.+?), length (.+?), file size (.+?)","errorType":"error_code","errorClass":"FormatError","httpStatus":null,"severity":"critical","filePath":"influxdb3_catalog/src/format/mod.rs","lineNumber":199,"sourceCode":"\n    /// Header CRC32 checksum mismatch.\n    #[error(\"header CRC32 mismatch: expected {expected:#010x}, actual {actual:#010x}\")]\n    HeaderCrc32Mismatch { expected: u32, actual: u32 },\n\n    /// Payload CRC32 checksum mismatch.\n    #[error(\"payload CRC32 mismatch: expected {expected:#010x}, computed {computed:#010x}\")]\n    Crc32Mismatch { expected: u32, computed: u32 },\n\n    /// Unknown record type without UPGRADE_SAFE flag — hard error.\n    #[error(\"unknown record id {record_id} without UPGRADE_SAFE flag\")]\n    UnknownNonUpgradeSafeRecord { record_id: u16 },\n\n    /// Invalid record length.\n    #[error(\"invalid record length: {length}\")]\n    InvalidRecordLength { length: u32 },\n\n    /// Record data exceeds remaining file.\n    #[error(\n        \"record data exceeds file bounds: offset {offset}, length {length}, file size {file_size}\"\n    )]\n    RecordExceedsFile {\n        offset: u64,\n        length: u32,\n        file_size: u64,\n    },\n\n    /// File header is internally inconsistent (e.g. a reserved field is\n    /// nonzero).\n    #[error(\"invalid header: {reason}\")]\n    InvalidHeader { reason: &'static str },\n\n    /// A `RestoreCatalog` record was encountered during sync apply with an\n    /// empty preload. Callers on a persistence path must first load the\n    /// backup state off-lock via `preload_restore_for_records` /\n    /// `preload_restore_for_file` and pass the resulting `RestorePreload`\n    /// into the apply call.","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/format/mod.rs#L181-L217","documentation":"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.","triggerScenarios":"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.","commonSituations":"Power loss during catalog flush; rsync/cp of a live data directory; running out of disk causing partial writes; incomplete restore from object store.","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."],"exampleFix":"// before: cp -r /var/lib/influxdb3/* /backup  (while running)\n// after: stop influxdb3, then copy\n// systemctl stop influxdb3 && cp -r /var/lib/influxdb3 /backup","handlingStrategy":"validation","validationCode":"// Verify expected file size before open (compare to checkpoint manifest)\nlet sz = fs::metadata(&path)?.len();\nif sz < expected_min_size_from_manifest {\n    return Err(format!(\"{} truncated: {} < {} bytes\", path.display(), sz, expected_min_size_from_manifest));\n}","typeGuard":null,"tryCatchPattern":"match catalog.open() {\n    Err(e) if e.to_string().contains(\"exceeds file bounds\") => restore_latest_checkpoint()?,\n    other => other,\n}","preventionTips":["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"],"tags":["truncation","corruption","catalog","file-io"],"backgroundTag":"file-read-failed","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}