nats-io/nats-server · error

unable to plug TLS verify connection, config is nil

Error message

unable to plug TLS verify connection, config is nil

What it means

Raised in Server.plugTLSOCSPPeer (server/ocsp_peer.go:140) when the server tries to install OCSP peer-certificate verification hooks but the tlsConfigKind wrapper or its embedded *tls.Config is nil. OCSP stapling/verification for mTLS clients and leaf connections requires a fully constructed TLS config; without one there is nothing to plug the VerifyConnection callback into, so startup fails fast with certidp.ErrUnableToPlugTLSEmptyConfig.

Source

Thrown at server/ocsp_peer.go:140

			pcfg.AllowWhenCAUnreachable = allowWhenCAUnreachable
		default:
			return nil, &configErr{tk, fmt.Sprintf(certidp.ErrParsingPeerOptFieldGeneric, mk)}
		}
	}
	return pcfg, nil
}

func peerFromVerifiedChains(chains [][]*x509.Certificate) *x509.Certificate {
	if len(chains) == 0 || len(chains[0]) == 0 {
		return nil
	}
	return chains[0][0]
}

// plugTLSOCSPPeer will plug the TLS handshake lifecycle for client mTLS connections and Leaf connections
func (s *Server) plugTLSOCSPPeer(config *tlsConfigKind) (*tls.Config, bool, error) {
	if config == nil || config.tlsConfig == nil {
		return nil, false, errors.New(certidp.ErrUnableToPlugTLSEmptyConfig)
	}
	kind := config.kind
	isSpoke := config.isLeafSpoke
	tcOpts := config.tlsOpts
	if tcOpts == nil || tcOpts.OCSPPeerConfig == nil || !tcOpts.OCSPPeerConfig.Verify {
		return nil, false, nil
	}
	s.Debugf(certidp.DbgPlugTLSForKind, config.kind)
	// peer is a tls client
	if kind == kindStringMap[CLIENT] || (kind == kindStringMap[LEAF] && !isSpoke) {
		if !tcOpts.Verify {
			return nil, false, errors.New(certidp.ErrMTLSRequired)
		}
		return s.plugClientTLSOCSPPeer(config)
	}
	// peer is a tls server
	if kind == kindStringMap[LEAF] && isSpoke {
		return s.plugServerTLSOCSPPeer(config)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add a complete tls { cert_file, key_file, ca_file } configuration for the kind (clients and/or leaf) where OCSP peer verification is enabled
2. Ensure ocsp_peer verify options only appear under a section that also defines TLS
3. Re-run nats-server with the corrected config; if reloading, include both TLS and OCSP sections in the new config

Example fix

# before
ocsp_peers {
  verify: true
}
# after: TLS must exist for the same kind
tls {
  cert_file: "./server-cert.pem"
  key_file: "./server-key.pem"
  ca_file: "./ca.pem"
  verify: true
}
ocsp_peer {
  verify: true
  urls: ["http://ocsp.example.com"]
}

// validate the NATS config before startup:
// every section with ocsp_peer { verify: true } must also define tls { cert_file, key_file }
import yaml
cfg = yaml.safe_load(open('nats.conf'))
def check(section, name):
    tls = section.get('tls') or {}
    ocsp = (tls.get('ocsp_peer') or {})
    if ocsp.get('verify') and not tls.get('cert_file'):
        raise SystemExit(f'{name}: ocsp_peer.verify requires a full tls block')
for s in ('clients', 'leafnodes'):
    if s in cfg: check(cfg[s], s)

// Go: fail fast with a clear message when starting the server
if err := startServer(cfgPath); err != nil && strings.Contains(err.Error(), "unable to plug TLS verify connection, config is nil") {
    log.Fatalf("OCSP peer verification enabled but TLS config missing for this kind: %v", err)
}

When it happens

Trigger: enableOCSP or reloadOCSP invokes plugTLSOCSPPeer with a nil config pointer, or a config whose tlsConfig field is nil — typically when OCSP peer verification (ocsp_peer config with verify: true) is enabled without a TLS config block defined for that kind (client or leaf).

Common situations: Setting ocsp_peer verify options in the config but omitting the tls {} block for clients or leaf nodes; a config reload that clears TLS settings while OCSP options remain; copy-pasting OCSP config into a section without TLS.

Understand the failure class

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

Related errors

• OCSP peer verification for client connections requires TLS v
• unable to register client OCSP verification
• invalid chain link
• no available OCSP servers
• no hostport specified

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