nats-io/nats-server · error

Could not parse snapshot peerstate correctly

Error message

Could not parse snapshot peerstate correctly

What it means

While processing a catchup batch that should contain exactly a snapshot entry and a peerstate entry, the peerstate could not be decoded from the received entry — the pair is malformed relative to what the leader should send. The node cannot apply partial peerstate, so the catchup is restarted rather than proceeding with bad membership data.

Source

Thrown at server/raft.go:4760

		// Check if we are catching up. If we are here we know the leader did not have all of the entries
		// so make sure this is a snapshot entry. If it is not start the catchup process again since it
		// means we may have missed additional messages.
		if catchingUp {
			// This means we already entered into a catchup state but what the leader sent us did not match what we expected.
			// Snapshots and peerstate will always be together when a leader is catching us up in this fashion.
			if len(ae.entries) != 2 || ae.entries[0].Type != EntrySnapshot || ae.entries[1].Type != EntryPeerState {
				n.warn("Expected first catchup entry to be a snapshot and peerstate, will retry")
				n.cancelCatchup()
				n.Unlock()
				return
			}

			if ps, err := decodePeerState(ae.entries[1].Data); err == nil {
				n.processPeerState(ps)
				// Also need to copy from client's buffer.
				ae.entries[0].Data = copyBytes(ae.entries[0].Data)
			} else {
				n.warn("Could not parse snapshot peerstate correctly")
				n.cancelCatchup()
				n.Unlock()
				return
			}

			// Inherit state from appendEntry with the leader's snapshot.
			hadPreviousSnapshot := n.snapfile != _EMPTY_

			snap := &snapshot{
				lastTerm:  ae.pterm,
				lastIndex: ae.pindex,
				peerstate: encodePeerState(&peerState{n.peerNames(), n.csz, n.extSt}),
				data:      ae.entries[0].Data,
			}
			// Install the leader's snapshot as our own.
			if err := n.installSnapshot(snap); err != nil {
				n.setWriteErrLocked(err)
				n.Unlock()

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Retry happens automatically via catchup restart
2. Check for version mismatch between leader and follower altering entry encoding
3. Report recurring parse failures with both node versions

When it happens

Trigger: Thrown at server/raft.go:4760 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/183df5863332879f. Report an issue: GitHub.