nats-io/nats-server · error

snapshot check failed: %w

Error message

snapshot check failed: %w

What it means

Wraps the underlying error from a snapshot check during a stream snapshot/backup operation. The file store runs a catch-up read to verify the snapshot state is consistent; if that check call returns an error, the snapshot fails with this message and the in-progress count (sips) is decremented. It guards against producing backups from an inconsistent state.

Source

Thrown at server/filestore.go:12915

	// Only allow one at a time.
	if fs.sips > 0 {
		fs.mu.Unlock()
		return nil, ErrStoreSnapshotInProgress
	}
	// Mark us as snapshotting
	fs.sips += 1
	fs.mu.Unlock()

	if checkMsgs {
		ld, err := fs.checkMsgs()
		clearSips := func() {
			fs.mu.Lock()
			fs.sips--
			fs.mu.Unlock()
		}
		if err != nil {
			clearSips()
			return nil, fmt.Errorf("snapshot check failed: %w", err)
		}
		if ld != nil && len(ld.Msgs) > 0 {
			clearSips()
			return nil, fmt.Errorf("snapshot check detected %d bad messages", len(ld.Msgs))
		}
	}

	pr, pw := net.Pipe()

	// Set a write deadline here to protect ourselves.
	if deadline > 0 {
		pw.SetWriteDeadline(time.Now().Add(deadline))
	}

	// We can add to our stream while snapshotting but not "user" delete anything.
	var state StreamState
	fs.FastState(&state)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped cause (%w) and fix the underlying I/O or state error.
2. Retry the snapshot after write load subsides; quiesce publishers during snapshot.
3. Verify the stream data directory integrity; restore from backup if corruption is reported.
4. Ensure adequate disk space and that the server has not hit file descriptor limits.

// Go: inspect the wrapped error
if err != nil {
    cause := errors.Unwrap(err)
    log.Printf("snapshot check failed, cause=%v", cause)
    // fix cause then re-attempt snapshot
}

When it happens

Trigger: Stream snapshot (e.g. via the JetStream API backup/consumer leader transfer flows) where the internal check read (ld lookup) returns an I/O or state error.

Common situations: Snapshotting a file-backed stream concurrently with heavy writes or catchup activity; disk I/O failures while reading messages for verification.

Related errors

• snapshot check detected %d bad messages
• no interest
• no flow response
• unknown compression algorithm
• name required

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