nats-io/nats-server · error · ApiError

max_waiting must not be negative

Error message

max_waiting must not be negative

What it means

Consumer config validation: MaxWaiting (bound on outstanding pull requests for a pull consumer) was given a negative value, which is meaningless as a bound. The MaxWaiting field of the consumer create/update request is the input at fault.

Source

Thrown at server/consumer.go:622

	JsDefaultMaxAckPending = 1000
	// JsDefaultPinnedTTL is the default grace period for the pinned consumer to send a new request before a new pin
	// is picked by a server.
	JsDefaultPinnedTTL = 2 * time.Minute
)

// Helper function to set consumer config defaults from above.
func setConsumerConfigDefaults(config *ConsumerConfig, streamCfg *StreamConfig, lim *JSLimitOpts, accLim *JetStreamAccountLimits, pedantic bool) *ApiError {
	// Setup default of -1, meaning no limit for MaxDeliver.
	if config.MaxDeliver == 0 || config.MaxDeliver < -1 {
		if pedantic && config.MaxDeliver < -1 {
			return NewJSPedanticError(errors.New("max_deliver must be set to -1"))
		}
		config.MaxDeliver = -1
	}
	// Setup zero defaults.
	if config.MaxWaiting < 0 {
		if pedantic {
			return NewJSPedanticError(errors.New("max_waiting must not be negative"))
		}
		config.MaxWaiting = 0
	}
	if config.MaxAckPending < -1 {
		if pedantic {
			return NewJSPedanticError(errors.New("max_ack_pending must be set to -1"))
		}
		config.MaxAckPending = -1
	}
	if config.MaxRequestBatch < 0 {
		if pedantic {
			return NewJSPedanticError(errors.New("max_batch must not be negative"))
		}
		config.MaxRequestBatch = 0
	}
	if config.MaxRequestExpires < 0 {
		if pedantic {
			return NewJSPedanticError(errors.New("max_expires must not be negative"))

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set max_waiting to 0 (server default) or a positive number
2. Omit the field from the consumer configuration

When it happens

Trigger: Thrown at server/consumer.go:622 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/6a69514aa868e4a0. Report an issue: GitHub.