nats-io/nats-server · error · ApiError

max_deliver must be set to -1

Error message

max_deliver must be set to -1

What it means

Consumer config validation in setConsumerConfigDefaults: MaxDeliver was set below -1 (e.g. -5). Only 0 (treated as unlimited, coerced to -1) and values >= -1 are legal; with pedantic mode enabled, MaxDeliver < -1 is rejected instead of silently coerced.

Source

Thrown at server/consumer.go:615

	JsAckWaitDefault = 30 * time.Second
	// JsDeleteWaitTimeDefault is the default amount of time we will wait for non-durable
	// consumers to be in an inactive state before deleting them.
	JsDeleteWaitTimeDefault = 5 * time.Second
	// JsFlowControlMaxPending specifies default pending bytes during flow control that can be outstanding.
	JsFlowControlMaxPending = 32 * 1024 * 1024
	// JsDefaultMaxAckPending is set for consumers with explicit ack that do not set the max ack pending.
	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 {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set max_deliver to -1 for unlimited deliveries or to a positive integer
2. Omit the field to accept the default
3. Disable pedantic mode only if silent coercion is acceptable

When it happens

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