nats-io/nats-server · error

max_payload (%v) cannot be higher than max_pending (%v)

Error message

max_payload (%v) cannot be higher than max_pending (%v)

What it means

validateOptions rejects the config when max_payload exceeds max_pending: the server must be able to buffer at least a full maximum-size message, so the internal pending/producer limits must be >= max_payload. Both configured values are printed; the combination is impossible to satisfy at runtime.

Source

Thrown at server/server.go:1172

func validatePinnedCerts(pinned PinnedCertSet) error {
	re := regexp.MustCompile("^[a-f0-9]{64}$")
	for certId := range pinned {
		entry := strings.ToLower(certId)
		if !re.MatchString(entry) {
			return fmt.Errorf("error parsing 'pinned_certs' key %s does not look like lower case hex-encoded sha256 of DER encoded SubjectPublicKeyInfo", entry)
		}
	}
	return nil
}

func validateOptions(o *Options) error {
	if o.LameDuckDuration > 0 && o.LameDuckGracePeriod >= o.LameDuckDuration {
		return fmt.Errorf("lame duck grace period (%v) should be strictly lower than lame duck duration (%v)",
			o.LameDuckGracePeriod, o.LameDuckDuration)
	}
	if int64(o.MaxPayload) > o.MaxPending {
		return fmt.Errorf("max_payload (%v) cannot be higher than max_pending (%v)",
			o.MaxPayload, o.MaxPending)
	}
	if o.ServerName != _EMPTY_ && strings.Contains(o.ServerName, " ") {
		return errors.New("server name cannot contain spaces")
	}
	// Check that the trust configuration is correct.
	if err := validateTrustedOperators(o); err != nil {
		return err
	}
	// Check on leaf nodes which will require a system
	// account when gateways are also configured.
	if err := validateLeafNode(o); err != nil {
		return err
	}
	// Check that authentication is properly configured.
	if err := validateAuth(o); err != nil {
		return err
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Raise max_pending to at least max_payload
2. Lower max_payload below the configured max_pending
3. Align both to sane defaults (e.g. max_payload 1MB, max_pending 64MB)

When it happens

Trigger: Thrown at server/server.go:1172 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/3972ad312e0764e3. Report an issue: GitHub.