{"record":{"id":"179191f643d66320","repo":"nsqio/nsq","slug":"failed-to-build-tls-config-s","errorCode":null,"errorMessage":"failed to build TLS config - %s","messagePattern":"failed to build TLS config - (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nsqd/nsqd.go","lineNumber":125,"sourceCode":"\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to lock data-path: %v\", err)\n\t}\n\n\tif opts.MaxDeflateLevel < 1 || opts.MaxDeflateLevel > 9 {\n\t\treturn nil, errors.New(\"--max-deflate-level must be [1,9]\")\n\t}\n\n\tif opts.ID < 0 || opts.ID >= 1024 {\n\t\treturn nil, errors.New(\"--node-id must be [0,1024)\")\n\t}\n\n\tif opts.TLSClientAuthPolicy != \"\" && opts.TLSRequired == TLSNotRequired {\n\t\topts.TLSRequired = TLSRequired\n\t}\n\n\ttlsConfig, err := buildTLSConfig(opts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to build TLS config - %s\", err)\n\t}\n\tif tlsConfig == nil && opts.TLSRequired != TLSNotRequired {\n\t\treturn nil, errors.New(\"cannot require TLS client connections without TLS key and cert\")\n\t}\n\tn.tlsConfig = tlsConfig\n\n\tclientTLSConfig, err := buildClientTLSConfig(opts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to build client TLS config - %s\", err)\n\t}\n\tn.clientTLSConfig = clientTLSConfig\n\n\tif opts.AuthHTTPRequestMethod != \"post\" && opts.AuthHTTPRequestMethod != \"get\" {\n\t\treturn nil, errors.New(\"--auth-http-request-method must be post or get\")\n\t}\n\n\tfor _, v := range opts.E2EProcessingLatencyPercentiles {\n\t\tif v <= 0 || v > 1 {","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/nsqio/nsq/blob/85cf10c09c6c3c86160d6f0eb156f62d0efc1648/nsqd/nsqd.go#L107-L143","documentation":"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').","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\n--tls-cert=/etc/nsqd/nsqd.pem\n--tls-key=/etc/nsqd/old.key   # mismatched after rotation\n\n# after\n--tls-cert=/etc/nsqd/nsqd.pem\n--tls-key=/etc/nsqd/nsqd.key   # matching pair from the same issuance","handlingStrategy":"validation","validationCode":"// preflight the pair exactly like the server will\nif _, err := tls.LoadX509KeyPair(certFile, keyFile); err != nil {\n\tlog.Fatalf(\"bad cert/key pair: %v\", err)\n}\nif caFile != \"\" {\n\tb, err := os.ReadFile(caFile)\n\tif err != nil { log.Fatal(err) }\n\tif !x509.NewCertPool().AppendCertsFromPEM(b) {\n\t\tlog.Fatal(\"root CA file is not valid PEM\")\n\t}\n}","typeGuard":null,"tryCatchPattern":"n, err := nsqd.New(opts)\nif err != nil && strings.Contains(err.Error(), \"failed to build TLS config\") {\n\t// cert material problem: fix files/permissions, then restart; not retryable as-is\n}","preventionTips":["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"],"tags":["nsqd","tls","certificates","config","startup"],"backgroundTag":null,"analyzedSha":"85cf10c09c6c3c86160d6f0eb156f62d0efc1648","analyzedAt":"2026-08-16T00:53:05.009Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}