nats-io/nats-server · error

%d append entries pending

Error message

%d append entries pending

What it means

Advisory: the count of append entries cached in memory for fast apply (n.pae) has reached paeWarnThreshold. Beyond this the cache stops growing to bound memory; it is a signal that commit/application throughput is lagging proposal intake, not an error.

Source

Thrown at server/raft.go:5167

	}
	return nil
}

// cachePendingEntry saves append entries in memory for faster processing during applyCommit.
// Only save so many however to avoid memory bloat.
func (n *raft) cachePendingEntry(ae *appendEntry) {
	// Invalidate any cache entry at this index, we might have
	// stored it previously with a different value.
	if pae, ok := n.pae[n.pindex]; ok {
		n.paeBytes -= n.entryStoreSize(pae)
		delete(n.pae, n.pindex)
	}
	if l := uint64(len(n.pae)); l < paeDropThreshold && n.paeBytes < paeDropBytes {
		prev := n.paeBytes
		n.pae[n.pindex], l = ae, l+1
		n.paeBytes += n.entryStoreSize(ae)
		if l >= paeWarnThreshold && l%paeWarnModulo == 0 {
			n.warn("%d append entries pending", len(n.pae))
		} else if b := n.paeBytes; b >= paeWarnBytes {
			// Only log on transition past another paeWarnBytesModulo.
			if b/paeWarnBytesModulo != prev/paeWarnBytesModulo {
				n.warn("%d append entries pending, %s", l, friendlyBytes(b))
			}
		}
	}
}

// entryStoreSize returns the byte size of the given append entry as stored in our WAL.
// Lock should be held.
func (n *raft) entryStoreSize(ae *appendEntry) uint64 {
	if ae == nil || ae.buf == nil {
		return 0
	}
	if n.wtype == FileStorage {
		return fileStoreMsgSize(_EMPTY_, nil, ae.buf)
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check what is slowing the apply loop (consumers, downstream systems)
2. Scale the node or reduce proposal pressure if the warning persists
3. No correctness impact — entries beyond the cache are loaded from the WAL

When it happens

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