nats-io/nats-server · error

bad pending entry, sequence [%d] out of range

Error message

bad pending entry, sequence [%d] out of range

What it means

Sanity check while copying pending entries in consumerMemStore.Update: a pending-ack entry references a stream sequence at or below the AckFloor (or otherwise outside the valid range), meaning the state says a message is awaiting ack that should already have been acked.

Source

Thrown at server/memstore.go:2776

func (o *consumerMemStore) Update(state *ConsumerState) error {
	// Sanity checks.
	if state.AckFloor.Consumer > state.Delivered.Consumer {
		return fmt.Errorf("bad ack floor for consumer")
	}
	if state.AckFloor.Stream > state.Delivered.Stream {
		return fmt.Errorf("bad ack floor for stream")
	}

	// Copy to our state.
	var pending map[uint64]*Pending
	var redelivered map[uint64]uint64
	if len(state.Pending) > 0 {
		pending = make(map[uint64]*Pending, len(state.Pending))
		for seq, p := range state.Pending {
			pending[seq] = &Pending{p.Sequence, p.Timestamp}
			if seq <= state.AckFloor.Stream || seq > state.Delivered.Stream {
				return fmt.Errorf("bad pending entry, sequence [%d] out of range", seq)
			}
		}
	}
	if len(state.Redelivered) > 0 {
		redelivered = make(map[uint64]uint64, len(state.Redelivered))
		for seq, dc := range state.Redelivered {
			redelivered[seq] = dc
		}
	}

	// Replace our state.
	o.mu.Lock()
	defer o.mu.Unlock()

	// Check to see if this is an outdated update.
	if state.Delivered.Consumer < o.state.Delivered.Consumer || state.AckFloor.Stream < o.state.AckFloor.Stream {
		return ErrStoreOldUpdate
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Drop stale pending entries that fall below the AckFloor before calling Update
2. Rebuild the consumer state if pending and ack floor disagree persistently

When it happens

Trigger: Thrown at server/memstore.go:2776 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/a822f3d6eb92f900. Report an issue: GitHub.