nats-io/nats-server · error

the minimum version should be at least 2.8.0

Error message

the minimum version should be at least 2.8.0

What it means

checkLeafMinVersionConfig rejects minimum versions older than 2.8.0 because leaf node features (such as the min_version mechanism itself and account-bound leaf connections) require at least 2.8.0. When the parsed version is valid but below 2.8.0, this error is returned. Called from validateLeafNode and parseLeafNodes.

Source

Thrown at server/leafnode.go:362

		return nil
	}
	// If we are here we have both leaf nodes and gateways defined, make sure there
	// is a system account defined.
	if o.SystemAccount == _EMPTY_ {
		return fmt.Errorf("leaf nodes and gateways (both being defined) require a system account to also be configured")
	}
	if err := validatePinnedCerts(o.LeafNode.TLSPinnedCerts); err != nil {
		return fmt.Errorf("leafnode: %v", err)
	}
	return nil
}

func checkLeafMinVersionConfig(mv string) error {
	if ok, err := versionAtLeastCheckError(mv, 2, 8, 0); !ok || err != nil {
		if err != nil {
			return fmt.Errorf("invalid leafnode's minimum version: %v", err)
		} else {
			return fmt.Errorf("the minimum version should be at least 2.8.0")
		}
	}
	return nil
}

// Used to validate user names in LeafNode configuration.
// - rejects mix of single and multiple users.
// - rejects duplicate user names.
func validateLeafNodeAuthOptions(o *Options) error {
	if len(o.LeafNode.Users) == 0 {
		return nil
	}
	if o.LeafNode.Username != _EMPTY_ {
		return fmt.Errorf("can not have a single user/pass and a users array")
	}
	if o.LeafNode.Nkey != _EMPTY_ {
		return fmt.Errorf("can not have a single nkey and a users array")
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Raise min_version to "2.8.0" or later
2. Remove the min_version key to accept defaults
3. Upgrade all leaf/serving servers so an up-to-date minimum is safe

Example fix

// before
leafnodes { min_version: "2.7.1" }
// after
leafnodes { min_version: "2.8.0" }

if mv := cfg.LeafNodes.MinVersion; mv != "" {
  v, _ := semver.NewVersion(mv)
  floor, _ := semver.NewVersion("2.8.0")
  if v != nil && v.LessThan(floor) {
    return fmt.Errorf("min_version %s is below required 2.8.0", mv)
  }
}

When it happens

Trigger: leafnodes { min_version: "2.x.y" } with x < 8 (e.g. "2.6.2", "2.7.4") during option validation or leaf node config parsing.

Common situations: Configs copied from very old NATS documentation or installations that were upgraded in place; operators pinning minimum versions below the supported floor.

Related errors

• invalid leafnode's minimum version: %v
• minimum version required
• connection rejected since minimum version required is
• remote leaf node URL %q cannot be used in FIPS-140 mode when
• leaf nodes and gateways (both being defined) require a syste

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