nats-io/nats-server · error

connection rejected since minimum version required is

Error message

connection rejected since minimum version required is

What it means

ErrLeafNodeMinVersionRejected is the leafnode protocol error prefix used when rejecting a remote due to leafnodes.min_version. The server sends it as a protocol -ERR message ('connection rejected since minimum version required is "x.y.z"') before closing, and the soliciting leaf checks for this string (server/leafnode.go:3527) to apply the leafNodeMinVersionReconnectDelay instead of hammering the hub.

Source

Thrown at server/errors.go:223

	// 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)

	// ErrMappingDestinationNotEnoughArgs is returned when the mapping destination function is not passed enough arguments
	ErrMappingDestinationNotEnoughArgs = fmt.Errorf("%w: not enough arguments passed to the function", ErrInvalidMappingDestination)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Upgrade the leaf node binary to a version >= the hub's leafnodes.min_version.
2. Temporarily lower leafnodes.min_version on the hub until all leaves are upgraded.
3. If this appears in hub logs, treat it as informational: the remote leaf is too old and is being rejected by design.

Example fix

// before: leaf 2.9.x reconnects to hub with min_version 2.10.0
// after
# on the leaf host
nats-server --version   # confirm
# upgrade leaf to >= 2.10.0 and restart

func isMinVersionRejected(errStr string) bool {
    return strings.Contains(errStr, server.ErrLeafNodeMinVersionRejected.Error())
}

if isMinVersionRejected(errStr) {
    // apply leafNodeMinVersionReconnectDelay instead of immediate retry
    delayReconnect()
}

When it happens

Trigger: Hub has leafnodes.min_version set and receives a CONNECT from a leaf below that version: it sends fmt.Sprintf("%s %q", ErrLeafNodeMinVersionRejected, mv) via sendErrAndErr and closes with MinimumVersionRequired (server/leafnode.go:2273). The soliciting side detects the prefix in errStr during reconnect handling.

Common situations: Mixed-version leaf/hub deployments; a hub config adds min_version during an upgrade; a leaf that keeps reconnecting rapidly and gets delayed by leafNodeMinVersionReconnectDelay.

Related errors

• minimum version required
• attempted to connect to leaf node port
• remote leafnode has same cluster name
• leafnodes disabled
• attempted to connect to wrong port

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