nats-io/nats-server · error

unsupported minimum TLS version: %s

Error message

unsupported minimum TLS version: %s

What it means

The server rejects a configured TLS MinVersion below TLS 1.2. NATS enforces 1.2 as the minimum acceptable protocol floor; any lower constant (TLS 1.0/1.1) in the config makes TLS config construction fail before the server starts.

Source

Thrown at server/opts.go:5890

		config.ClientAuth = tls.RequireAndVerifyClientCert
	}
	// Add in CAs if applicable.
	if tc.CaFile != _EMPTY_ {
		rootPEM, err := os.ReadFile(tc.CaFile)
		if err != nil || rootPEM == nil {
			return nil, err
		}
		pool := x509.NewCertPool()
		ok := pool.AppendCertsFromPEM(rootPEM)
		if !ok {
			return nil, fmt.Errorf("failed to parse root ca certificate")
		}
		config.ClientCAs = pool
	}
	// Allow setting TLS minimum version.
	if tc.MinVersion > 0 {
		if tc.MinVersion < tls.VersionTLS12 {
			return nil, fmt.Errorf("unsupported minimum TLS version: %s", tls.VersionName(tc.MinVersion))
		}
		config.MinVersion = tc.MinVersion
	}

	return &config, nil
}

// MergeOptions will merge two options giving preference to the flagOpts
// if the item is present.
func MergeOptions(fileOpts, flagOpts *Options) *Options {
	if fileOpts == nil {
		return flagOpts
	}
	if flagOpts == nil {
		return fileOpts
	}
	// Merge the two, flagOpts override
	opts := *fileOpts

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set min_version to "TLS1.2" (or remove the option to use the default).
2. If the version is supplied programmatically, pass tls.VersionTLS12 or higher only.
3. Upgrade legacy clients to support TLS 1.2+ instead of lowering the server floor.
4. Check the config value type/spelling for the version constant.

Example fix

// before
tls: { min_version: "TLS1.1" }
// after
tls: { min_version: "TLS1.2" }

// Reject sub-TLS1.2 min_version in config before applying it
if tc.MinVersion > 0 && tc.MinVersion < tls.VersionTLS12 {
    return fmt.Errorf("min_version must be TLS1.2 or higher, got %s", tls.VersionName(tc.MinVersion))
}

func minVersionSupported(v uint16) bool {
    return v == 0 || v >= tls.VersionTLS12
}

if err := checkTLSConfig(tc); err != nil {
    return fmt.Errorf("fix tls.min_version in config: %w", err)
}

When it happens

Trigger: Setting the min_version option in a TLS config block to a value below tls.VersionTLS12 (e.g. 0x0301 for TLS 1.1, or a hand-written decimal in JSON/YAML config).

Common situations: Copied legacy config from an old NATS server (pre-2.x allowed lower versions), manually specifying the numeric version constant incorrectly, or trying to interoperate with ancient clients still on TLS 1.1.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• unable to plug TLS verify connection, config is nil
• OCSP peer verification for client connections requires TLS v
• unable to register client OCSP verification
• websocket requires TLS configuration
• error parsing certificate %d/%d: %v

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