clockworklabs/SpacetimeDB · error · io::Error

error reading commit header: {e}

Error message

error reading commit header: {e}

What it means

When decoding a commit from the commitlog, the reader first reads the fixed 14-byte header; an UnexpectedEof there is treated as a clean end of the log (Ok(None)). Any other I/O error while reading the header is re-wrapped with 'error reading commit header', preserving the original error kind. In practice this indicates an environmental problem such as permissions or a device error, not a normal end-of-log.

Source

Thrown at crates/commitlog/src/commit.rs:91

                Ok(Some(Self {
                    min_tx_offset,
                    epoch: Commit::DEFAULT_EPOCH,
                    n,
                    len,
                }))
            }
        }
    }

    fn decode_v1<R: Read>(mut reader: R) -> io::Result<Option<Self>> {
        let mut hdr = [0; Self::LEN];
        if let Err(e) = reader.read_exact(&mut hdr) {
            if e.kind() == io::ErrorKind::UnexpectedEof {
                return Ok(None);
            }

            return Err(io::Error::new(e.kind(), format!("error reading commit header: {e}")));
        }
        match &mut hdr.as_slice() {
            [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] => Ok(None),
            buf => {
                let min_tx_offset = buf.get_u64().map_err(|e| decode_header_error(e, "min_tx_offset"))?;
                let epoch = buf.get_u64().map_err(|e| decode_header_error(e, "epoch"))?;
                let n = buf.get_u16().map_err(|e| decode_header_error(e, "n"))?;
                let len = buf.get_u32().map_err(|e| decode_header_error(e, "len"))?;

                Ok(Some(Self {
                    min_tx_offset,
                    epoch,
                    n,
                    len,
                }))
            }
        }
    }

View on GitHub (pinned to 524b4487d9)

Solutions

  1. Check OS logs (dmesg, journalctl) for device/IO errors and test the disk
  2. Verify ownership and permissions of the commitlog repository files for the host process
  3. Restore the repository from a snapshot or backup if the medium is failing
Defensive patterns

Strategy: try-catch

Try / catch

use std::io;
loop {
    match commit.decode(&mut reader) {
        Ok(None) => break, // clean end of log
        Ok(Some(c)) => { /* handle commit */ }
        Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
        Err(e) => return Err(e), // UnexpectedEof is normalized to Ok(None) by the library;
                                 // any error here is environmental — surface it, don't retry
    }
}

Prevention

When it happens

Trigger: Reading a commit whose 14-byte header read fails with a non-UnexpectedEof error: EACCES or EIO on a segment file, storage detached mid-read.

Common situations: Disk or permission trouble on the db directory while the host reads its log; files chowned or chmodded under a running process.

Related errors

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/ba3cf912c2c3fb36. Report an issue: GitHub.