nats-io/nats-server · error

Leader falling behind, stepping down: pindex %d, commit %d,

Error message

Leader falling behind, stepping down: pindex %d, commit %d, applied %d, WAL size %s

What it means

A warning logged by proposeLocked() when isLeaderOverrun() detects the leader's write-ahead log has grown beyond safe limits (pindex/commit/applied divergence, WAL size reported). The leader steps down so a peer with a healthier WAL can take over, protecting the group from unbounded log growth.

Source

Thrown at server/raft.go:994

	return n.proposeLocked(term, data)
}

func (n *raft) proposeLocked(term uint64, data []byte) error {
	// Check state under lock, we might not be leader anymore.
	if state := n.State(); state != Leader || term != n.term {
		n.debug("Proposal ignored, not leader (state: %v, cterm: %d, term: %d)", state, term, n.term)
		return errNotLeader
	}

	// Error if we had a previous write error.
	if werr := n.werr; werr != nil {
		return werr
	}

	if n.isLeaderOverrun() {
		var state StreamState
		n.wal.FastState(&state)
		n.warn("Leader falling behind, stepping down: pindex %d, commit %d, applied %d, WAL size %s", n.pindex, n.commit, n.applied, friendlyBytes(state.Bytes))
		// Stepdown without leader transfer, likely all replicas will be overrun, and we need time to recover.
		n.stepdownLocked(noLeader)
		n.overrunCount++
		return errNotLeader
	}
	n.prop.push(newProposedEntry(newEntry(EntryNormal, data), _EMPTY_, n.term))
	return nil
}

// ProposeMulti will propose multiple entries at once.
// This should only be called on the leader.
func (n *raft) ProposeMulti(term uint64, entries []*Entry) error {
	if n.tryFastPathProposeMulti(term, entries) {
		return nil
	}
	n.Lock()
	defer n.Unlock()
	// Check state under lock, we might not be leader anymore.

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Investigate why apply/consume rate lags proposals (slow disk, WAL write errors)
  2. Check n.werr and disk health for the raft WAL storage
  3. Allow the new leader to catch up; monitor WAL size after failover
  4. Scale consumers or increase snapshot compaction frequency
Defensive patterns

Strategy: fallback

When it happens

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