nats-io/nats-server · error

minimum version required

Error message

minimum version required

What it means

ErrMinimumVersionRequired is returned when a connection is not at the minimum version required. It is used mainly for leaf node connections: when leafnodes.min_version is configured and the connecting leaf's version is too old, processLeafConnect sends a rejection and returns this sentinel, which the parse loop (server/client.go:1574) special-cases because the connection was already closed.

Source

Thrown at server/errors.go:220

	// ErrMalformedSubject is returned when a subscription is made with a subject that does not conform to subject rules.
	ErrMalformedSubject = errors.New("malformed subject")

	// ErrSubscribePermissionViolation is returned when processing of a subscription fails due to permissions.
	ErrSubscribePermissionViolation = errors.New("subscribe permission violation")

	// ErrNoTransforms signals no subject transforms are available to map this subject.
	ErrNoTransforms = errors.New("no matching transforms available")

	// ErrCertNotPinned is returned when pinned certs are set and the certificate is not in it
	ErrCertNotPinned = errors.New("certificate not pinned")

	// ErrDuplicateServerName is returned when processing a server remote connection and
	// the server reports that this server name is already used in the cluster.
	ErrDuplicateServerName = errors.New("duplicate server name")

	// ErrMinimumVersionRequired is returned when a connection is not at the minimum version required.
	ErrMinimumVersionRequired = errors.New("minimum version required")
	// ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used
	// when rejecting a remote due to leafnodes.min_version.
	ErrLeafNodeMinVersionRejected = errors.New("connection rejected since minimum version required is")

	// ErrInvalidMappingDestination is used for all subject mapping destination errors
	ErrInvalidMappingDestination = errors.New("invalid mapping destination")

	// ErrInvalidMappingDestinationSubject is used to error on a bad transform destination mapping
	ErrInvalidMappingDestinationSubject = fmt.Errorf("%w: invalid transform", ErrInvalidMappingDestination)

	// ErrMappingDestinationNotUsingAllWildcards is used to error on a transform destination not using all of the token wildcards
	ErrMappingDestinationNotUsingAllWildcards = fmt.Errorf("%w: not using all of the token wildcard(s)", ErrInvalidMappingDestination)

	// ErrUnknownMappingDestinationFunction is returned when a subject mapping destination contains an unknown mustache-escaped mapping function.
	ErrUnknownMappingDestinationFunction = fmt.Errorf("%w: unknown function", ErrInvalidMappingDestination)

	// ErrMappingDestinationIndexOutOfRange is returned when the mapping destination function is passed an out of range wildcard index value for one of it's arguments
	ErrMappingDestinationIndexOutOfRange = fmt.Errorf("%w: wildcard index out of range", ErrInvalidMappingDestination)

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Upgrade the connecting leaf node's nats-server (or client) binary to at least the configured leafnodes.min_version.
  2. If old leaves must be supported temporarily, lower or remove leafnodes.min_version on the hub.
  3. Check versions on both sides (nats-server --version) before rolling out min_version enforcement.

Example fix

# before (hub)
leafnodes {
  min_version: "2.10.0"
}
# leaf runs 2.9.x -> rejected
# after
# upgrade leaf: nats-server --version >= 2.10.0, or set min_version: "2.9.0" temporarily
Defensive patterns

Strategy: validation

Validate before calling

// check before connecting a leaf
if versionCompare(leafVersion, requiredMinVersion) < 0 {
    return fmt.Errorf("leaf version %s < required %s", leafVersion, requiredMinVersion)
}

Try / catch

if errors.Is(err, server.ErrMinimumVersionRequired) {
    log.Fatalf("leaf node too old: upgrade to >= leafnodes.min_version")
}

Prevention

When it happens

Trigger: A leaf node connects to a server configured with leafnodes { min_version: "x.y.z" } and the leaf's protocol version is below that minimum; processLeafConnect (server/leafnode.go:2275) closes the connection with MinimumVersionRequired and returns ErrMinimumVersionRequired.

Common situations: Upgrading hub servers to a version that enforces leafnodes.min_version while edge leaf servers remain on old binaries; mixed-version fleets after a rolling upgrade; ignoring leafnodes.min_version in config.

Related errors

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