nats-io/nats-server · error

max_ack_pending for all consumers would be %v which exceeds

Error message

max_ack_pending for all consumers would be %v which exceeds the limit of %v

What it means

MQTT consumer-creation check: adding this subscription's maxAckPending to the session-wide running total (tmaxack) would exceed mqttMaxAckTotalLimit. It protects the server from one MQTT session fanning out more in-flight unacked messages than the global cap allows.

Source

Thrown at server/mqtt.go:5819

	ackWait := opts.MQTT.AckWait
	if ackWait == 0 {
		ackWait = mqttDefaultAckWait
	}
	maxAckPending := int(opts.MQTT.MaxAckPending)
	if maxAckPending == 0 {
		maxAckPending = mqttDefaultMaxAckPending
	}

	sess.mu.Lock()
	pubRelSubject := sess.pubRelSubject
	tmaxack := sess.tmaxack
	idHash := sess.idHash
	id := sess.id
	sess.mu.Unlock()

	// Check that the limit of subs' maxAckPending are not going over the limit
	if after := tmaxack + maxAckPending; after > mqttMaxAckTotalLimit {
		return fmt.Errorf("max_ack_pending for all consumers would be %v which exceeds the limit of %v",
			after, mqttMaxAckTotalLimit)
	}

	ccr := &CreateConsumerRequest{
		Stream: mqttOutStreamName,
		Config: ConsumerConfig{
			DeliverSubject: pubRelDeliverySubject,
			Durable:        mqttPubRelConsumerDurablePrefix + idHash,
			AckPolicy:      AckExplicit,
			DeliverPolicy:  DeliverNew,
			FilterSubject:  pubRelSubject,
			AckWait:        ackWait,
			MaxAckPending:  maxAckPending,
			MemoryStorage:  opts.MQTT.ConsumerMemoryStorage,
		},
	}
	if opts.MQTT.ConsumerInactiveThreshold > 0 {
		ccr.Config.InactiveThreshold = opts.MQTT.ConsumerInactiveThreshold

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Lower the consumer's MaxAckPending setting
  2. Unsubscribe unused consumers to release their share of the total budget
  3. Split sessions if the workload legitimately needs more pending acks
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at server/mqtt.go:5819 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/7aaf8b3a254b4c01. Report an issue: GitHub.