sled was already opened with a LEAF_FANOUT const generic of

Error message

sled was already opened with a LEAF_FANOUT const generic of {}, and this may not be changed after initial creation. Please use Db::import / Db::export to migrate, if you wish to change the system's format.

What it means

A sled database persists the LEAF_FANOUT it was created with, and the on-disk format depends on it. check_compatibility (via verify_or_store) compares the const generic used at this open against the stored value and fails if they differ, because changing fanout in place would corrupt the layout.

Solutions

Open the database with the same LEAF_FANOUT it was created with (match the original constant)
Use Db::export on the old-fanout database and Db::import into a database opened with the new fanout to migrate
If the data is disposable, delete the data directory and re-open with the new fanout

Example fix

// before
let db = config.open::<4>()?; // db was created with 8
// after
let db = config.open::<8>()?; // match creation-time fanout, or export/import to migrate

Defensive patterns

Strategy: validation

Validate before calling

// read the persisted fanout before opening, or centralize the constant
pub const DB_LEAF_FANOUT: usize = 4; // single source of truth, never change for existing data

Try / catch

match Db::open(&path) {
    Ok(db) => db,
    Err(e) if e.to_string().contains("LEAF_FANOUT") => {
        eprintln!("open with the fanout the db was created with, or export/import");
        return Err(e.into());
    }
    Err(e) => return Err(e.into()),
}

Prevention

Use one shared constant for LEAF_FANOUT across the codebase and never change it for existing deployments
Never hardcode the fanout at multiple call sites
Use Db::export/Db::import for any intentional format migration
Tag deployments with the fanout they require

When it happens

Trigger: Opening an existing database directory with Config::open::<N>() where N differs from the fanout used when the database was first created (e.g. originally open::<8>(), now open::<4>()).

Common situations: Refactoring code and tweaking the const generic; switching branches where the fanout constant differs; running an older/newer deployment of the same app against the same data directory.

Related errors

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

Appendix: source

Thrown at src/heap.rs:292

                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!(
                            "sled was already opened with a LEAF_FANOUT const generic of {}, \
                                and this may not be changed after initial creation. Please use \
                                Db::import / Db::export to migrate, if you wish to change the \
                                system's format.",
                            lf2
                        ),
                    ))
                } else {
                    Ok(())
                }
            }
        }
    }

    fn serialize(&self) -> Vec<u8> {
        // format: 64 bytes in total, with the last 4 being a LE crc32

View on GitHub (pinned to e449d17111)