nats-io/nats-server · error

lame duck grace period (%v) should be strictly lower than la

Error message

lame duck grace period (%v) should be strictly lower than lame duck duration (%v)

What it means

validateOptions rejects the config when lame_duck_grace_period is greater than or equal to lame_duck_duration (and duration > 0): the grace period must fit strictly inside the lame duck duration, otherwise the shutdown sequencing (grace then close) cannot be scheduled. Both values are printed for comparison.

Source

Thrown at server/server.go:1168

		}
	}
	return nil
}

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
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Lower lame_duck_grace_period below lame_duck_duration (strictly less than)
2. Scale both values together, e.g. duration 30s with grace 10s
3. Omit grace period if the default relative value is acceptable

When it happens

Trigger: Thrown at server/server.go:1168 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/1d5086a4deb5c9f0. Report an issue: GitHub.