{"record":{"id":"e003f672eece9051","repo":"tursodatabase/turso","slug":"mvcc-logical-log-frame-checksum-mismatch-at-offset","errorCode":null,"errorMessage":"MVCC logical log frame checksum mismatch at offset {offset}","messagePattern":"MVCC logical log frame checksum mismatch at offset (.+?)","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"cli/sync_server.rs","lineNumber":1090,"sourceCode":"        extension_size\n    } else {\n        0\n    };\n    let trailer_start = offset\n        .checked_add(header_size)\n        .and_then(|value| value.checked_add(payload_size))\n        .and_then(|value| value.checked_add(extension_size))\n        .ok_or_else(|| anyhow!(\"MVCC logical log frame offset overflow\"))?;\n    let frame_end = trailer_start\n        .checked_add(MVCC_TX_TRAILER_SIZE)\n        .ok_or_else(|| anyhow!(\"MVCC logical log frame end overflow\"))?;\n    if frame_end > log.len() {\n        return Ok(None);\n    }\n    let expected_crc = crc32c::crc32c_append(running_crc, &log[offset..trailer_start]);\n    let stored_crc = read_u32_le(log, trailer_start)?;\n    if stored_crc != expected_crc {\n        return Err(anyhow!(\n            \"MVCC logical log frame checksum mismatch at offset {offset}\"\n        ));\n    }\n    let end_magic = read_u32_le(log, trailer_start + 4)?;\n    if end_magic != MVCC_TX_END_MAGIC {\n        return Err(anyhow!(\n            \"invalid MVCC logical log frame end magic at offset {offset}\"\n        ));\n    }\n    Ok(Some((frame_end, stored_crc)))\n}\n\nfn read_u32_le(buf: &[u8], offset: usize) -> Result<u32> {\n    let bytes = buf\n        .get(offset..offset + 4)\n        .ok_or_else(|| anyhow!(\"buffer too short for u32 at offset {offset}\"))?;\n    Ok(u32::from_le_bytes(bytes.try_into().unwrap()))\n}","sourceCodeStart":1072,"sourceCodeEnd":1108,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/cli/sync_server.rs#L1072-L1108","documentation":"Frame CRCs are chained: the chain seeds from crc32c of the header salt, and each frame's trailer stores crc32c_append(running_crc, header+payload+extension). A mismatch at the reported offset means this frame's bytes changed — or an earlier frame was inserted, dropped, or came from a log with a different salt, breaking the chain at this point. Even later frames that look intact cannot be trusted because the running CRC state is wrong.","triggerScenarios":"scan_mvcc_log walking frames where crc32c_append(running_crc, frame bytes) differs from the stored trailer CRC: bit corruption inside one frame, an earlier frame inserted or removed (the chain breaks at the next frame), or frames replayed against a log with a different header salt.","commonSituations":"Unreliable storage (failing disk, network filesystem); copying a log while it is being appended so frames are half-written; splicing frames between logs of different generations/salts; crash between frame write and trailer write.","solutions":["Re-pull the entire logical log from a known-good snapshot — one mismatch invalidates the chain and every later delta.","Never splice frames between logs or generations; the chain is salted per log header.","Compare the log with the producer's copy (sha256) to locate the first divergent byte and confirm the corruption is local.","If mismatches recur on one node, investigate storage durability (fsync behavior, failing hardware)."],"exampleFix":"// before\nlet snapshot = scan_mvcc_log(&log)?; // errors: frame checksum mismatch at offset N\n\n// after: do not serve deltas past the break — re-pull the whole log\nlet snapshot = match scan_mvcc_log(&log) {\n    Ok(snapshot) => snapshot,\n    Err(err) if err.to_string().contains(\"frame checksum mismatch\") => {\n        rebootstrap_log_from_server()?\n    }\n    Err(err) => return Err(err),\n};","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match scan_mvcc_log(&log) {\n    Ok(snapshot) => { /* serve deltas from crc_by_offset */ }\n    Err(err) if err.to_string().contains(\"frame checksum mismatch\") => {\n        // chain broken: re-pull the whole log; deltas past the break are\n        // untrustworthy even if later frames look intact\n    }\n    Err(err) => return Err(err),\n}","preventionTips":["Re-pull the entire log on any frame CRC failure; never resume mid-chain.","Never splice frames between logs — the chain is salted by the header salt.","Ensure frames and trailers are written and fsynced together before announcement.","Hash-compare with the producer's copy to confirm where divergence began."],"tags":["mvcc","turso","sync","crc32c","log-corruption"],"backgroundTag":"checksum-mismatch","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}