{"record":{"id":"97a0a6b5dd29758a","repo":"influxdata/influxdb","slug":"crc32-checksum-mismatch","errorCode":null,"errorMessage":"crc32 checksum mismatch","messagePattern":"crc32 checksum mismatch","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"influxdb3_wal/src/serialize.rs","lineNumber":20,"sourceCode":"//! buffered in memory before writing it in a single PUT operation to object store, this works\n//! a little differently than a traditional WAL that appends.\n\nuse crate::WalContents;\nuse byteorder::{BigEndian, ReadBytesExt};\nuse bytes::Bytes;\nuse std::io::Cursor;\nuse std::mem::size_of;\nuse thiserror::Error;\n\n#[derive(Debug, Error)]\npub enum Error {\n    #[error(\"Invalid wal file identifier\")]\n    InvalidWalFile,\n\n    #[error(\"WAL file too small: expected at least {expected} bytes, but got {actual} bytes\")]\n    WalFileTooSmall { expected: usize, actual: usize },\n\n    #[error(\"crc32 checksum mismatch\")]\n    Crc32Mismatch,\n\n    #[error(\"bitcode error: {0}\")]\n    Bitcode(#[from] bitcode::Error),\n\n    #[error(\"IO error: {0}\")]\n    Io(#[from] std::io::Error),\n\n    #[error(\"try from slice error {0}\")]\n    TryFromSlice(#[from] std::array::TryFromSliceError),\n}\n\npub(crate) type Result<T, E = Error> = std::result::Result<T, E>;\n\n/// The first bytes written into a wal file to identify it and its version.\nconst FILE_TYPE_IDENTIFIER: &[u8] = b\"idb3.001\";\n\n#[inline(always)]","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_wal/src/serialize.rs#L2-L38","documentation":"serialize::Error::Crc32Mismatch is raised when the CRC32 checksum stored in a WAL file does not match the checksum computed over the bytes actually read. Each WAL file ends with a crc32 of its contents; a mismatch means the file's payload was corrupted in transit or at rest, so the library refuses to deserialize it rather than replaying garbage.","triggerScenarios":"verify_file_type_and_deserialize reads the file body and trailing crc32 (serialize.rs:73) and the computed checksum differs from the stored one — bit rot, partial writes, or a file modified after being written.","commonSituations":"Hardware/storage corruption; interrupted writes that committed data bytes but not (correct) trailer bytes; manually editing a .wal file; copying files with a lossy transfer; object-store layers that don't preserve byte fidelity.","solutions":["Treat the file as corrupt: restore it from backup, or skip it if losing that segment's buffered (not yet snapshot) data is acceptable.","Check storage health (disk SMART, filesystem errors, dmesg) for underlying corruption causes.","Re-copy the file with checksum verification (e.g. rsync -c) if it was transferred between hosts.","Avoid any post-write modification of WAL files; never edit them by hand."],"exampleFix":"# before: suspect corrupted file\n# verify_file_type_and_deserialize(...) -> Crc32Mismatch\n# after: restore from backup\naws s3 cp s3://backup/wal/1/1712345678/0000000008.wal wal/1/1712345678/0000000008.wal","handlingStrategy":"try-catch","validationCode":"// independently verify crc32 before handing bytes to the library\nlet expected = u32::from_be_bytes(bytes[bytes.len()-4..].try_into()?);\nlet computed = crc32fast::hash(&bytes[..bytes.len()-4]);\nif expected != computed { /* corrupt: restore/skip */ }","typeGuard":null,"tryCatchPattern":"match verify_file_type_and_deserialize(&bytes) {\n    Err(serialize::Error::Crc32Mismatch) => restore_from_backup_or_skip(path),\n    other => other?,\n}","preventionTips":["Run filesystem/SMART monitoring to catch storage corruption early.","Copy WAL files only with checksum-verified tools (rsync -c, checksum compare).","Never edit .wal files in place.","Keep backups of WAL/object-store contents for restore."],"tags":["rust","wal","corruption","crc32","serialization"],"backgroundTag":"checksum-mismatch","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"}