nats-io/nats-server · error

Quorum paused, falling behind: commit %d != applied %d, WAL

Error message

Quorum paused, falling behind: commit %d != applied %d, WAL size %s

What it means

Backpressure event: the commit-applied gap exceeded the pause threshold (count or bytes), so the node pauses the apply/quorum path to avoid unbounded WAL growth while the upper layer catches up. While paused, the node expects to converge, likely via a snapshot from the leader; catchup may be cancelled.

Source

Thrown at server/raft.go:4654

				if catchingUp {
					n.cancelCatchup()
				}
				n.Unlock()
				return
			}
			// Once we're sufficiently below the threshold, we continue again. We'll likely receive a snapshot
			// from the leader.
			n.quorumPaused = false
			var state StreamState
			n.wal.FastState(&state)
			n.warn("Quorum resumed: commit %d, applied %d, WAL size %s", commit, applied, friendlyBytes(state.Bytes))
		} else if n.overrun(diff, pauseQuorumThreshold, pauseQuorumBytes) {
			// It takes a while until we reach the pause threshold, but once we do we enter a "cooldown period".
			n.quorumPaused = true
			n.overrunCount++
			var state StreamState
			n.wal.FastState(&state)
			n.warn("Quorum paused, falling behind: commit %d != applied %d, WAL size %s", commit, applied, friendlyBytes(state.Bytes))
			if catchingUp {
				n.cancelCatchup()
			}
			n.Unlock()
			return
		}
	}

	if ae.pterm != n.pterm || ae.pindex != n.pindex {
		// Check if this is a lower or equal index than what we were expecting.
		if ae.pindex <= n.pindex {
			n.debug("AppendEntry detected pindex less than/equal to ours: [%d:%d] vs [%d:%d]", ae.pterm, ae.pindex, n.pterm, n.pindex)
			var success bool

			if ae.pindex < n.commit {
				// If we have already committed this entry, just mark success.
				success = true
				n.debug("AppendEntry pindex %d below commit %d, marking success", ae.pindex, n.commit)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Speed up the apply path (scale consumers, fix slow downstream sinks)
2. Let the pause/resume cycle or incoming snapshot resolve the gap
3. Tune stream limits if pauses recur under normal load

When it happens

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