{"record":{"id":"b904e4766955d0f9","repo":"EpicGames/lore","slug":"level-header-file-has-unsupported-version-expected","errorCode":null,"errorMessage":"level header file has unsupported version {}, expected {}","messagePattern":"level header file has unsupported version (.+?), expected (.+?)","errorType":"exception","errorClass":"io::Error (InvalidData)","httpStatus":null,"severity":"error","filePath":"lore-storage/src/local/fan_out.rs","lineNumber":408,"sourceCode":"            std::io::ErrorKind::UnexpectedEof,\n            format!(\n                \"level header file is {} bytes, expected {expected}\",\n                bytes.len()\n            ),\n        ));\n    }\n    header.as_mut_bytes().copy_from_slice(&bytes[..expected]);\n    if header.magic != MARKER_MAGIC {\n        return Err(std::io::Error::new(\n            std::io::ErrorKind::InvalidData,\n            format!(\n                \"level header file has invalid magic 0x{:08x}, expected 0x{:08x}\",\n                header.magic, MARKER_MAGIC\n            ),\n        ));\n    }\n    if header.version != MARKER_VERSION {\n        return Err(std::io::Error::new(\n            std::io::ErrorKind::InvalidData,\n            format!(\n                \"level header file has unsupported version {}, expected {}\",\n                header.version, MARKER_VERSION\n            ),\n        ));\n    }\n    Ok(Some(header.bucket_count as usize))\n}\n\n/// The serialized level header as the one segment a gather writes.\n///\n/// Fixed size — the header's length is a compile-time constant — and behind a pointer, because\n/// [`lore_io::StableBufList`] requires a segment to keep its address when the value moves and the\n/// ring backend moves the segment list into its operation entry after taking the pointers.\nstruct LevelHeaderSegment(Box<[u8; size_of::<LevelMarkerHeader>()]>);\n\nimpl lore_io::StableBufList for LevelHeaderSegment {","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/EpicGames/lore/blob/074eb0b0d1194c997d7cf28b55519e3e197b3e23/lore-storage/src/local/fan_out.rs#L390-L426","documentation":"After the magic check, `read_level_header_file` validates `header.version` against `MARKER_VERSION`. A mismatch means the marker file was written by a different (older or newer) lore-storage on-disk format that this build cannot read. It fails with `ErrorKind::InvalidData` reporting both versions.","triggerScenarios":"Opening a store whose level marker files were written by a different lore-storage version — typically upgrading or downgrading the library, or mixing store directories between versions.","commonSituations":"Rolling back a dependency version, copying a store directory between machines running different builds, or a beta/nightly format change without a migration path.","solutions":["Upgrade lore-storage to the version that wrote `MARKER_VERSION` (the 'expected' value in the message shows what this build needs).","Run any provided migration tooling to convert old-format stores.","Re-seed/rebuild the store if no migration path exists."],"exampleFix":"// before\nlet header = read_level_marker(dir).await?; // fails: unsupported version 2\n\n// after\n// pin the crate version that wrote the store, or migrate first:\n// Cargo.toml: lore-storage = \"= <version matching MARKER_VERSION>\"\nlet header = read_level_marker(dir).await?;","handlingStrategy":"try-catch","validationCode":"let bytes = tokio::fs::read(&header_path).await?;\nlet version = u32::from_le_bytes(bytes[4..8].try_into()?);\nif version != MARKER_VERSION { /* migrate or use matching crate version */ }","typeGuard":null,"tryCatchPattern":"match read_level_marker(dir).await {\n    Err(e) if e.kind() == io::ErrorKind::InvalidData => {\n        eprintln!(\"store written by a different lore-storage version; migrate first\");\n    }\n    other => other?,\n}","preventionTips":["Pin the lore-storage version in CI so all machines read stores with the same format.","Run migrations before opening stores written by older versions.","Don't downgrade the dependency against an existing store directory."],"tags":["io","version-mismatch","compatibility"],"backgroundTag":"schema-validation-failed","analyzedSha":"074eb0b0d1194c997d7cf28b55519e3e197b3e23","analyzedAt":"2026-09-13T09:00:57.509Z","contentChangedAt":"2026-09-13T09:00:57.509Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}