spacejam/sled · critical

encountered corrupted settings cookie with mismatched CRC.

Error message

encountered corrupted settings cookie with mismatched CRC.

What it means

The persistent settings cookie (the on-disk block recording format version and leaf fanout) embeds a CRC32 checksum. On deserialize, the stored CRC does not match the CRC computed over the first 60 bytes, so the settings block is considered corrupt and opening fails rather than proceeding with garbage configuration.

Solutions

1. Restore the database from a backup, since the settings block is unrecoverable in place
2. Check disk health (SMART) and filesystem integrity before retrying
3. If the data is expendable, delete the database files and re-create/re-import it
4. Verify file transfer integrity (checksums) if the corruption appeared after copying

// before opening, sanity-check the file exists and has a plausible size
let meta = std::fs::metadata(&path)?;
if meta.len() < 64 { return Err(anyhow!("db file suspiciously small/corrupt")); }

match Db::open(&path) {
    Ok(db) => db,
    Err(e) if e.to_string().contains("corrupted settings cookie") => {
        // restore from backup or recreate
        restore_backup(&path)?;
        Db::open(&path)?
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Opening a database whose settings cookie bytes were corrupted: torn writes during a crash/power loss, disk/bit rot, or manual byte editing of the database file.

Common situations: Recovering a database after an unclean shutdown or power failure; copying database files with a tool that truncates or corrupts them; hardware failure on the storage device.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• crc mismatch - data corruption detected
• corrupt frame length
• crc mismatch for read of batch frame
• 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/6060cf2ea48d810e. Report an issue: GitHub.

Appendix: source

Thrown at src/heap.rs:264

            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                std::fs::write(settings_path, self.serialize())
            }
            Err(e) => Err(e),
        }
    }

    fn deserialize(buf: &[u8]) -> io::Result<PersistentSettings> {
        let mut cursor = buf;
        let mut buf = [0_u8; 64];
        cursor.read_exact(&mut buf)?;

        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",
            )),
        }
    }

View on GitHub (pinned to e449d17111)