{"record":{"id":"362a4afbed2d5d27","repo":"astrid-runtime/astrid","slug":"astrid-volume-record-checksum-mismatch","errorCode":null,"errorMessage":"Astrid volume record checksum mismatch","messagePattern":"Astrid volume record checksum mismatch","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage/src/volume/hosted/recover.rs","lineNumber":464,"sourceCode":"    read_exact_at(file, header.payload_offset, &mut payload)?;\n    verify_record_checksum(header, &payload)?;\n    Ok(Some(payload))\n}\n\nfn verify_record_checksum(header: &RecordHeader, payload: &[u8]) -> io::Result<()> {\n    let mut hasher = blake3::Hasher::new_derive_key(\"astrid volume record v1\");\n    hasher.update(&header.sequence.to_le_bytes());\n    hasher.update(&[header.operation as u8]);\n    let name = header.name.as_str().as_bytes();\n    let name_len =\n        u16::try_from(name.len()).map_err(|_| invalid_transition(\"region name too long\"))?;\n    hasher.update(&name_len.to_le_bytes());\n    hasher.update(&header.logical_offset.to_le_bytes());\n    hasher.update(&header.payload_len.to_le_bytes());\n    hasher.update(name);\n    hasher.update(payload);\n    if hasher.finalize().as_bytes() != &header.checksum {\n        return Err(io::Error::new(\n            io::ErrorKind::InvalidData,\n            \"Astrid volume record checksum mismatch\",\n        ));\n    }\n    Ok(())\n}\n\nfn read_commit(\n    file: &File,\n    offset: u64,\n    durable_len: u64,\n    sequence: u64,\n) -> io::Result<Option<(RecordHeader, Vec<u8>)>> {\n    let Some(header) = read_header(file, offset, durable_len)? else {\n        return Ok(None);\n    };\n    if header.operation != Operation::Commit\n        || header.name.as_str() != COMMIT_REGION","sourceCodeStart":446,"sourceCodeEnd":482,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage/src/volume/hosted/recover.rs#L446-L482","documentation":"Each volume record's BLAKE3 checksum (keyed with \"astrid volume record v1\" over the sequence, name, logical offset, payload length, name bytes, and payload) is verified when the payload is read back. The recomputed hash does not match the checksum stored in the header, so the record's bytes are corrupt or the header fields were altered.","triggerScenarios":"verify_record_checksum, called from read_record_payload during recovery, reads a record (name + payload + header fields) whose recomputed BLAKE3 digest differs from header.checksum — corrupt payload bytes, wrong key/format version, or misinterpreted header fields.","commonSituations":"Bit rot or bad sectors flipping payload bytes on disk; recovery run against a file written by a different volume format/key version ('astrid volume record v1' mismatch); torn writes without fs-level protection; manual editing or copying of the volume file.","solutions":["Restore the volume from backup; checksummed records that fail cannot be trusted.","Confirm the file was written by the same format version/key derivation ('astrid volume record v1'); version mismatches fail every record.","If every record fails, suspect the wrong file or a format change rather than random corruption — check the volume's format/version markers.","Run disk/filesystem integrity checks if failures are localized or recurring."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match recover_from_headers(&file) {\n    Err(e) if e.to_string().contains(\"checksum mismatch\") => {\n        // record untrustworthy: restore from backup; if ALL records fail, suspect format/version mismatch\n    }\n    other => other?,\n}","preventionTips":["Keep the volume format/key-derivation version consistent across reads and writes.","Deploy on storage with end-to-end integrity protection (ZFS/btrfs or similar) to catch bit rot early.","Snapshot volumes regularly; verify snapshots before pruning originals.","Never modify volume files with external tools."],"tags":["storage","checksum","data-corruption","blake3"],"backgroundTag":"checksum-mismatch","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}