spacejam/sled · error

encountered unknown version number when reading settings…

Error message

encountered unknown version number when reading settings cookie

What it means

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.

Solutions

1. Upgrade to the sled version that wrote the database (check the version bytes with a hex dump of the settings cookie)
2. Migrate data via Db::export from the newer version and Db::import into the older one, or vice versa
3. If corruption is suspected and data is expendable, recreate the database from scratch

// pin the sled version used to write the data; record it alongside the data dir
let expected_sled_version = "1.0.0"; // compare with the version your binary links

match Db::open(&path) {
    Ok(db) => db,
    Err(e) if e.to_string().contains("unknown version number") => {
        // data was written by a different sled version: migrate via export/import
        migrate_with_compatible_version(&path)?
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• sled was already opened with a LEAF_FANOUT const generic of
• Db's LEAF_FANOUT const generic must be 3 or greater.
• encountered corrupted settings cookie with mismatched CRC.
• failed to fill whole buffer
• failed to write whole buffer

AI-assisted analysis of spacejam/sled@e449d17111 (2026-09-12). Data as JSON: /api/errors/2b5471ba46245375. Report an issue: GitHub.

Appendix: source

Thrown at src/heap.rs:276

        let version = u16::from_le_bytes([buf[0], buf[1]]);

        let crc_actual = (crc32fast::hash(&buf[0..60]) ^ 0xAF).to_le_bytes();
        let crc_expected = &buf[60..];

        if crc_actual != crc_expected {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "encountered corrupted settings cookie with mismatched CRC.",
            ));
        }

        match version {
            1 => {
                let leaf_fanout =
                    u64::from_le_bytes(buf[2..10].try_into().unwrap());
                Ok(PersistentSettings::V1 { leaf_fanout })
            }
            _ => Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "encountered unknown version number when reading settings cookie",
            )),
        }
    }

    fn check_compatibility(
        &self,
        other: &PersistentSettings,
    ) -> io::Result<()> {
        use PersistentSettings::*;

        match (self, other) {
            (V1 { leaf_fanout: lf1 }, V1 { leaf_fanout: lf2 }) => {
                if lf1 != lf2 {
                    Err(io::Error::new(
                        io::ErrorKind::Unsupported,
                        format!(

View on GitHub (pinned to e449d17111)