What causes "failed to build TLS config - %s" in nsqio/nsq?

Check paths and readability as the nsqd user: sudo -u nsqd cat /etc/nsqd/cert.pem >/dev/null

failed to build TLS config - %s

Error message

failed to build TLS config - %s

What it means

nsqd.New builds its server TLS config when --tls-cert and --tls-key are set: it loads the key pair with tls.LoadX509KeyPair and, if --tls-root-ca-file is set, reads and parses that CA bundle. Failures are wrapped as 'failed to build TLS config'. Typical causes: cert/key files missing or unreadable, malformed PEM, a cert that does not match the key, an unreadable CA file, or a CA bundle that is not valid PEM ('failed to append certificate to pool').

Source

Thrown at nsqd/nsqd.go:125

	if err != nil {
		return nil, fmt.Errorf("failed to lock data-path: %v", err)
	}

	if opts.MaxDeflateLevel < 1 || opts.MaxDeflateLevel > 9 {
		return nil, errors.New("--max-deflate-level must be [1,9]")
	}

	if opts.ID < 0 || opts.ID >= 1024 {
		return nil, errors.New("--node-id must be [0,1024)")
	}

	if opts.TLSClientAuthPolicy != "" && opts.TLSRequired == TLSNotRequired {
		opts.TLSRequired = TLSRequired
	}

	tlsConfig, err := buildTLSConfig(opts)
	if err != nil {
		return nil, fmt.Errorf("failed to build TLS config - %s", err)
	}
	if tlsConfig == nil && opts.TLSRequired != TLSNotRequired {
		return nil, errors.New("cannot require TLS client connections without TLS key and cert")
	}
	n.tlsConfig = tlsConfig

	clientTLSConfig, err := buildClientTLSConfig(opts)
	if err != nil {
		return nil, fmt.Errorf("failed to build client TLS config - %s", err)
	}
	n.clientTLSConfig = clientTLSConfig

	if opts.AuthHTTPRequestMethod != "post" && opts.AuthHTTPRequestMethod != "get" {
		return nil, errors.New("--auth-http-request-method must be post or get")
	}

	for _, v := range opts.E2EProcessingLatencyPercentiles {
		if v <= 0 || v > 1 {

View on GitHub (pinned to 85cf10c09c)

Solutions

Check paths and readability as the nsqd user: sudo -u nsqd cat /etc/nsqd/cert.pem >/dev/null
Validate the pair matches: openssl x509 -in cert.pem -pubkey -noout | openssl md5 vs openssl pkey -in key.pem -pubout | openssl md5 (pubkeys must be equal)
Confirm both files are PEM; re-issue the pair together if they mismatch
Verify --tls-root-ca-file is a readable PEM CA bundle

Example fix

# before
--tls-cert=/etc/nsqd/nsqd.pem
--tls-key=/etc/nsqd/old.key   # mismatched after rotation

# after
--tls-cert=/etc/nsqd/nsqd.pem
--tls-key=/etc/nsqd/nsqd.key   # matching pair from the same issuance

Defensive patterns

Strategy: validation

Validate before calling

// preflight the pair exactly like the server will
if _, err := tls.LoadX509KeyPair(certFile, keyFile); err != nil {
	log.Fatalf("bad cert/key pair: %v", err)
}
if caFile != "" {
	b, err := os.ReadFile(caFile)
	if err != nil { log.Fatal(err) }
	if !x509.NewCertPool().AppendCertsFromPEM(b) {
		log.Fatal("root CA file is not valid PEM")
	}
}

Try / catch

n, err := nsqd.New(opts)
if err != nil && strings.Contains(err.Error(), "failed to build TLS config") {
	// cert material problem: fix files/permissions, then restart; not retryable as-is
}

Prevention

Rotate cert and key atomically as a pair (single directory swap)
Run a pre-start exec that validates the pair as the service user
Mount secret files with read access for the nsqd user, and alert on zero-byte certs

When it happens

Trigger: Starting nsqd with --tls-cert=/etc/nsqd/cert.pem --tls-key=/etc/nsqd/key.pem where either file is absent, truncated, or the pair was regenerated on one side only; --tls-root-ca-file pointing at a file with non-PEM content or wrong permissions.

Common situations: Certificate rotation scripts updating cert but not key (or vice versa); secrets mounted into containers with wrong paths or empty files after a botched sync; permissions readable only by root while nsqd runs unprivileged; expired renewals leaving zero-byte files.

Understand the failure class

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

Related errors

AI-assisted analysis of nsqio/nsq@85cf10c09c (2026-08-16). Data as JSON: /api/errors/179191f643d66320. Report an issue: GitHub.