nats-io/nats-server · error

Canceling catchup for %q, could not subscribe to progress in

Error message

Canceling catchup for %q, could not subscribe to progress inbox: %v

What it means

While setting up catchup for a follower, the leader could not subscribe to the per-peer progress inbox used for flow control. Without that feedback channel, catchup would stall, so the catchup is aborted and any queued state is unwound.

Source

Thrown at server/raft.go:3645

		if q, ok := n.progress[peer]; ok && q == indexUpdatesQ {
			delete(n.progress, peer)
			if len(n.progress) == 0 {
				n.progress = nil
			}
		}
		// Check if this is a new peer and if so go ahead and propose adding them.
		_, exists := n.peers[peer]
		n.Unlock()
		if !exists {
			n.debug("Catchup done for %q, will add into peers", peer)
			n.ProposeAddPeer(peer)
		}
		indexUpdatesQ.unregister()
	}()

	if err != nil {
		// Without the progress subscription, there's no flow control, so catchup would stall.
		n.warn("Canceling catchup for %q, could not subscribe to progress inbox: %v", peer, err)
		return
	}
	if !leader {
		n.debug("Canceling catchup for %q, not leader anymore", peer)
		return
	}
	n.debug("Running catchup for %q [%d:%d] to [%d:%d]", peer, ar.term, ar.index, pterm, last)

	const maxOutstanding = 2 * 1024 * 1024 // 2MB for now.
	next, total, om := uint64(0), 0, make(map[uint64]int)

	sendNext := func() bool {
		for total <= maxOutstanding {
			next++
			if next > last {
				return true
			}
			ae, err := n.loadEntry(next)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the subscribe error for resource exhaustion (subs limit, memory)
2. Let the follower re-request catchup; a new attempt will retry the subscription
3. Scale down subscription pressure on the internal transport if this recurs

When it happens

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