nats-io/nats-server · error

Snapshot corrupt, checksums did not match

Error message

Snapshot corrupt, checksums did not match

What it means

The trailing 8-byte highwayhash checksum embedded in the snapshot file does not match the hash recomputed over the rest of the buffer, meaning the snapshot payload was corrupted (torn write, bit rot, or partial file). loadLastSnapshot refuses to trust the contents and returns the errSnapshotCorrupt sentinel so the caller falls back to WAL replay or a fresh snapshot from the leader.

Source

Thrown at server/raft.go:2046

	n.dios.release()

	if err != nil {
		n.warn("Error reading snapshot: %v", err)
		return nil, err
	}
	if len(buf) < minSnapshotLen {
		n.warn("Snapshot corrupt, too short")
		return nil, errSnapshotCorrupt
	}

	// Check to make sure hash is consistent.
	hoff := len(buf) - 8
	lchk := buf[hoff:]
	n.hh.Reset()
	n.hh.Write(buf[:hoff])
	var hb [highwayhash.Size64]byte
	if !bytes.Equal(lchk[:], n.hh.Sum(hb[:0])) {
		n.warn("Snapshot corrupt, checksums did not match")
		return nil, errSnapshotCorrupt
	}

	var le = binary.LittleEndian
	lps := le.Uint32(buf[16:])
	snap := &snapshot{
		lastTerm:  le.Uint64(buf[0:]),
		lastIndex: le.Uint64(buf[8:]),
		peerstate: buf[20 : 20+lps],
		data:      buf[20+lps : hoff],
	}

	// We had a bug in 2.9.12 that would allow snapshots on last index of 0.
	// Detect that and continue anyway, nothing else we can do about it.
	if snap.lastIndex == 0 {
		n.warn("Snapshot with last index 0 is invalid, cleaning up")
		os.Remove(n.snapfile)
		n.snapfile = _EMPTY_

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Delete or move aside the corrupt snapshot file so the node re-snapshots from the leader on next catchup
2. Verify disk health and filesystem durability (fsync/direct-io) settings that could allow torn writes
3. Restore a known-good snapshot backup if available to avoid full catchup

When it happens

Trigger: Thrown at server/raft.go:2046 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/eca47e50ca48ddd0. Report an issue: GitHub.