{"record":{"id":"2b5471ba46245375","repo":"spacejam/sled","slug":"encountered-unknown-version-number-when-reading-settings","errorCode":null,"errorMessage":"encountered unknown version number when reading settings cookie","messagePattern":"encountered unknown version number when reading settings cookie","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/heap.rs","lineNumber":276,"sourceCode":"        let version = u16::from_le_bytes([buf[0], buf[1]]);\n\n        let crc_actual = (crc32fast::hash(&buf[0..60]) ^ 0xAF).to_le_bytes();\n        let crc_expected = &buf[60..];\n\n        if crc_actual != crc_expected {\n            return Err(io::Error::new(\n                io::ErrorKind::InvalidData,\n                \"encountered corrupted settings cookie with mismatched CRC.\",\n            ));\n        }\n\n        match version {\n            1 => {\n                let leaf_fanout =\n                    u64::from_le_bytes(buf[2..10].try_into().unwrap());\n                Ok(PersistentSettings::V1 { leaf_fanout })\n            }\n            _ => Err(io::Error::new(\n                io::ErrorKind::InvalidData,\n                \"encountered unknown version number when reading settings cookie\",\n            )),\n        }\n    }\n\n    fn check_compatibility(\n        &self,\n        other: &PersistentSettings,\n    ) -> io::Result<()> {\n        use PersistentSettings::*;\n\n        match (self, other) {\n            (V1 { leaf_fanout: lf1 }, V1 { leaf_fanout: lf2 }) => {\n                if lf1 != lf2 {\n                    Err(io::Error::new(\n                        io::ErrorKind::Unsupported,\n                        format!(","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/spacejam/sled/blob/e449d17111f4a097e1c66b6db241962ccb6a4136/src/heap.rs#L258-L294","documentation":"The settings cookie's leading u16 version field is checked against the versions this build knows how to read. A cookie stamped with any version other than 1 cannot be deserialized, so the library refuses to open the database with misleading settings.","triggerScenarios":"Opening a database file written by a newer sled release whose settings-cookie version is > 1, or reading a corrupted cookie whose version bytes were scrambled into an unknown value.","commonSituations":"Downgrading the sled dependency (running an old binary against a newer on-disk format); moving a database between systems with different library versions; bit corruption in the first bytes of the cookie.","solutions":["Upgrade to the sled version that wrote the database (check the version bytes with a hex dump of the settings cookie)","Migrate data via Db::export from the newer version and Db::import into the older one, or vice versa","If corruption is suspected and data is expendable, recreate the database from scratch"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pin the sled version used to write the data; record it alongside the data dir\nlet expected_sled_version = \"1.0.0\"; // compare with the version your binary links","typeGuard":null,"tryCatchPattern":"match Db::open(&path) {\n    Ok(db) => db,\n    Err(e) if e.to_string().contains(\"unknown version number\") => {\n        // data was written by a different sled version: migrate via export/import\n        migrate_with_compatible_version(&path)?\n    }\n    Err(e) => return Err(e.into()),\n}","preventionTips":["Keep the sled dependency version in lockstep across all services that share a data directory","Document the on-disk format version next to deployments","Use Db::export/Db::import when upgrading or downgrading formats","Treat sudden version errors on known-good files as possible corruption"],"tags":["rust","versioning","compatibility","persistence"],"backgroundTag":"unsupported-enum-value","analyzedSha":"e449d17111f4a097e1c66b6db241962ccb6a4136","analyzedAt":"2026-09-12T01:23:10.985Z","contentChangedAt":"2026-09-12T01:23:10.985Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}