{"record":{"id":"1d8e49bb8d23d59f","repo":"clockworklabs/SpacetimeDB","slug":"segment-header-does-not-start-with-magic-expected","errorCode":null,"errorMessage":"segment header does not start with magic: expected {:02x?}, got {:02x?}","messagePattern":"segment header does not start with magic: expected (.+?), got (.+?)","errorType":"exception","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/commitlog/src/segment.rs","lineNumber":57,"sourceCode":"\n    pub fn write<W: io::Write>(&self, mut out: W) -> io::Result<()> {\n        out.write_all(&MAGIC)?;\n        out.write_all(&[self.log_format_version, self.checksum_algorithm, 0, 0])?;\n\n        Ok(())\n    }\n\n    pub fn decode<R: io::Read>(mut read: R) -> io::Result<Self> {\n        let mut buf = [0; Self::LEN];\n        read.read_exact(&mut buf).map_err(|e| {\n            io::Error::new(\n                e.kind(),\n                format!(\"failed to read segment header ({} bytes): {}\", Self::LEN, e),\n            )\n        })?;\n\n        if !buf.starts_with(&MAGIC) {\n            return Err(io::Error::new(\n                io::ErrorKind::InvalidData,\n                format!(\n                    \"segment header does not start with magic: expected {:02x?}, got {:02x?}\",\n                    MAGIC,\n                    &buf[..MAGIC.len()]\n                ),\n            ));\n        }\n\n        Ok(Self {\n            log_format_version: buf[MAGIC.len()],\n            checksum_algorithm: buf[MAGIC.len() + 1],\n        })\n    }\n\n    pub fn ensure_compatible(&self, max_log_format_version: u8, checksum_algorithm: u8) -> Result<(), String> {\n        if self.log_format_version > max_log_format_version {\n            return Err(format!(\"unsupported log format version: {}\", self.log_format_version));","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/commitlog/src/segment.rs#L39-L75","documentation":"The first 6 bytes of the file being opened do not equal the segment magic constant (ds)^2 (hex 28 64 73 29 5e 32), so the file is not a commitlog segment (InvalidData). Expect this from a wrong file, foreign content, or a corrupted header.","triggerScenarios":"Pointing CommitLogDir at a directory containing unrelated files whose names parse as segment offsets; a segment file overwritten or truncated by another program; garbage written over the header by disk corruption.","commonSituations":"Sharing a data directory with other tools; misconfigured paths (e.g. the WAL dir of another database); bit rot on old segments.","solutions":["List the directory and check which files are not real segments (magic check) - usually a path misconfiguration","Remove or quarantine the foreign file after confirming nothing else owns it","Restore genuinely corrupt segments from backup"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"fn is_segment_file(p: &std::path::Path) -> io::Result<bool> {\n    use std::io::Read as _;\n    let mut f = std::fs::File::open(p)?;\n    let mut magic = [0u8; 6];\n    match f.read_exact(&mut magic) {\n        Ok(()) => Ok(magic == *b\"(ds)^2\"),\n        Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => Ok(false),\n        Err(e) => Err(e),\n    }\n}","typeGuard":"fn is_bad_magic(e: &io::Error) -> bool {\n    e.kind() == io::ErrorKind::InvalidData\n        && e.to_string().contains(\"does not start with magic\")\n}","tryCatchPattern":null,"preventionTips":["Dedicate one directory to the commitlog; never share it with other tools' files","Validate directory contents (magic check) after restores or migrations","Alert on unexpected files in the log directory during startup"],"tags":["rust","commitlog","segment-header","magic-bytes","invalid-data","file-format"],"backgroundTag":"invalid-file-format","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}