{"record":{"id":"c60d2c59dbc05741","repo":"influxdata/influxdb","slug":"invalid-wal-file-identifier","errorCode":null,"errorMessage":"Invalid wal file identifier","messagePattern":"Invalid wal file identifier","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"influxdb3_wal/src/serialize.rs","lineNumber":14,"sourceCode":"//! Module for serializing and deserializing the contents of a single WAL file. Since the WAL is\n//! 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","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_wal/src/serialize.rs#L1-L32","documentation":"serialize::Error::InvalidWalFile is raised when the first bytes of a WAL file do not match the expected magic identifier/version header. Every WAL file begins with a small identifier block; if the reader cannot recognize it, the file is not considered a valid WAL file for this version and deserialization stops. This prevents misinterpreting arbitrary or foreign data as WAL contents.","triggerScenarios":"Calling verify_file_type_and_deserialize (serialize.rs:48) on a file whose leading magic bytes/version do not equal SIZE_V1's expected identifier — e.g. an empty file, a truncated file whose header was lost, or a file written by an incompatible version.","commonSituations":"Hand-editing or copying files into the WAL directory; restoring partial/corrupt backups; a version upgrade changing the WAL file identifier so old or new files are unreadable by the other version; pointing the WAL reader at a non-WAL file.","solutions":["Verify the file is a genuine WAL file produced by this version; if it is a foreign file, move it out of the WAL directory.","Check for version mismatch: files written by an older influxdb3 may need migration or must be replayed with the matching version.","Replace the corrupt file from a backup; skip it if you can tolerate losing that segment's buffered data.","Do not manually truncate WAL files — truncation that destroys the header produces exactly this error."],"exampleFix":"# before\ncp notes.txt /var/lib/influxdb3/wal/1/1712345678/0000000006.wal\n# after (only genuine WAL files in the directory)\ninfluxdb3 ...  # reader now parses all files with the correct magic identifier","handlingStrategy":"try-catch","validationCode":"// check the file starts with the WAL identifier before full parse\nfn has_wal_magic(bytes: &[u8], magic: &[u8]) -> bool { bytes.len() >= magic.len() && &bytes[..magic.len()] == magic }","typeGuard":"fn is_valid_wal_file(bytes: &[u8]) -> bool { bytes.len() >= 4 && bytes[0..4] == *b\"INFL\" /* actual magic from SIZE_V1 */ }","tryCatchPattern":"match verify_file_type_and_deserialize(&bytes) {\n    Err(serialize::Error::InvalidWalFile) => skip_or_quarantine(path),\n    other => other?,\n}","preventionTips":["Never place hand-created or copied arbitrary files into the WAL directory.","After version upgrades, replay old files with the writer's version or migrate them.","Do not truncate WAL files manually; the header must remain intact."],"tags":["rust","wal","serialization","magic-bytes","corruption"],"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"}