nats-io/nats-server · error · ApiError

max_bytes must not be negative

Error message

max_bytes must not be negative

What it means

A JetStream pedantic validation error thrown when MaxRequestMaxBytes (the maximum bytes a pull request may request) is negative. Byte counts cannot be negative; in pedantic mode the server rejects the config rather than silently clamping to 0 (server/consumer.go:646).

Source

Thrown at server/consumer.go:646

			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"))
		}
		config.MaxRequestExpires = 0
	}
	if config.MaxRequestMaxBytes < 0 {
		if pedantic {
			return NewJSPedanticError(errors.New("max_bytes must not be negative"))
		}
		config.MaxRequestMaxBytes = 0
	}
	if config.Heartbeat < 0 {
		if pedantic {
			return NewJSPedanticError(errors.New("idle_heartbeat must not be negative"))
		}
		config.Heartbeat = 0
	}
	if config.InactiveThreshold < 0 {
		if pedantic {
			return NewJSPedanticError(errors.New("inactive_threshold must not be negative"))
		}
		config.InactiveThreshold = 0
	}
	if config.PinnedTTL < 0 {
		if pedantic {
			return NewJSPedanticError(errors.New("priority_timeout must not be negative"))

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set MaxRequestMaxBytes to a positive integer of bytes or 0 for the server default.
2. Clamp budget computations to >= 0 before assignment.
3. Replace -1 'unlimited' convention with 0 for this field.
4. Run Validate(true) client-side before the API call.

Example fix

// before
bytes := quota - used // -2048
cc := nats.ConsumerConfig{MaxRequestMaxBytes: bytes}
// after
if bytes < 0 { bytes = 0 }
cc := nats.ConsumerConfig{MaxRequestMaxBytes: bytes}

if cfg.MaxRequestMaxBytes < 0 { return errors.New("max_bytes must not be negative") }

if _, err := js.AddConsumer(stream, &cc); err != nil && strings.Contains(err.Error(), "max_bytes") {
    cc.MaxRequestMaxBytes = 0
    _, err = js.AddConsumer(stream, &cc)
}

When it happens

Trigger: ConsumerConfig.MaxRequestMaxBytes < 0 supplied on consumer create/update with pedantic validation, e.g. MaxRequestMaxBytes: -1024 or a computed byte budget that went below zero.

Common situations: Byte-budget arithmetic (quota - usage) yielding negatives; operators using -1 for 'unlimited' (0 is the correct sentinel here); config templating with negative placeholder values.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• max_batch must not be negative
• got corrupted escaped character
• max_ack_pending must be set to -1
• max_expires must not be negative
• idle_heartbeat must not be negative

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/6da3700ce49cb682. Report an issue: GitHub.