nats-io/nats-server · error

Detected another leader with higher term, will stepdown

Error message

Detected another leader with higher term, will stepdown

What it means

An append-entry response carried a term higher than this node's current term (the responder is on a newer term). The node adopts the higher term, clears its vote, and steps down as leader — standard Raft behavior to converge on the newest term rather than continue an illegitimate leadership.

Source

Thrown at server/raft.go:5022

			n.sendHeartbeat()
		}

		arPool.Put(ar)
	} else if ar.reply != _EMPTY_ {
		// The remote node didn't commit the append entry, and they believe they
		// are behind and have specified a reply subject, so let's try to catch them up.
		// In this case ar.term was populated with the remote's pterm.
		n.catchupFollower(ar)
	} else {
		n.Lock()
		if ar.term > n.term {
			// The remote node didn't commit the append entry, it looks like
			// they are on a newer term than we are. Step down.
			// In this case ar.term was populated with the remote's term.
			n.term = ar.term
			n.vote = noVote
			n.writeTermVote()
			n.warn("Detected another leader with higher term, will stepdown")
			n.stepdownLocked(noLeader)
		}
		n.Unlock()
		// Either way, return back to pool.
		arPool.Put(ar)
	}
}

// handleAppendEntryResponse processes responses to append entries.
func (n *raft) handleAppendEntryResponse(sub *subscription, c *client, _ *Account, subject, reply string, msg []byte) {
	ar := decodeAppendEntryResponse(msg)
	if ar == nil {
		n.error("Received malformed append entry response")
		return
	}
	ar.reply = reply
	n.resp.push(ar)
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. No action needed; a new election in the higher term resolves leadership
2. Frequent occurrences suggest network partitions or a reinstated node with persisted newer state
3. Verify no removed node keeps rejoining with divergent state

When it happens

Trigger: Thrown at server/raft.go:5022 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/6836dc4a5ea5dec7. Report an issue: GitHub.