nats-io/nats-server · error

TLS Server private key must be present and valid

Error message

TLS Server private key must be present and valid

What it means

overrideTLS: -tls=true is active and a certificate was supplied, but opts.TLSKey is empty — the private key matching the certificate is missing, so the TLS configuration cannot be built.

Source

Thrown at server/opts.go:6493

func normalizeBasePath(p string) string {
	if len(p) == 0 {
		return "/"
	}
	// add leading slash
	if p[0] != '/' {
		p = "/" + p
	}
	return path.Clean(p)
}

// overrideTLS is called when at least "-tls=true" has been set.
func overrideTLS(opts *Options) error {
	if opts.TLSCert == _EMPTY_ {
		return errors.New("TLS Server certificate must be present and valid")
	}
	if opts.TLSKey == _EMPTY_ {
		return errors.New("TLS Server private key must be present and valid")
	}

	tc := TLSConfigOpts{}
	tc.CertFile = opts.TLSCert
	tc.KeyFile = opts.TLSKey
	tc.CaFile = opts.TLSCaCert
	tc.Verify = opts.TLSVerify
	tc.Ciphers = defaultCipherSuites()

	var err error
	opts.TLSConfig, err = GenTLSConfig(&tc)
	return err
}

// overrideCluster updates Options.Cluster if that flag "cluster" (or "cluster_listen")
// has explicitly be set in the command line. If it is set to empty string, it will
// clear the Cluster options.
func overrideCluster(opts *Options) error {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Supply the private key, e.g. --tlskey server.key
2. Set key_file alongside cert_file in the TLS config block
3. Check for misspelled flag or option names

When it happens

Trigger: Thrown at server/opts.go:6493 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

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