{"record":{"id":"d115810767665cb2","repo":"nsqio/nsq","slug":"failed-to-read-tls-root-ca-file-s-s","errorCode":null,"errorMessage":"failed to read TLS root CA file %s - %s","messagePattern":"failed to read TLS root CA file (.+?) - (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nsqadmin/nsqadmin.go","lineNumber":75,"sourceCode":"\t\treturn nil, errors.New(\"--http-client-tls-cert must be specified with --http-client-tls-key\")\n\t}\n\n\tn.httpClientTLSConfig = &tls.Config{\n\t\tInsecureSkipVerify: opts.HTTPClientTLSInsecureSkipVerify,\n\t}\n\tif opts.HTTPClientTLSCert != \"\" && opts.HTTPClientTLSKey != \"\" {\n\t\tcert, err := tls.LoadX509KeyPair(opts.HTTPClientTLSCert, opts.HTTPClientTLSKey)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to LoadX509KeyPair %s, %s - %s\",\n\t\t\t\topts.HTTPClientTLSCert, opts.HTTPClientTLSKey, err)\n\t\t}\n\t\tn.httpClientTLSConfig.Certificates = []tls.Certificate{cert}\n\t}\n\tif opts.HTTPClientTLSRootCAFile != \"\" {\n\t\ttlsCertPool := x509.NewCertPool()\n\t\tcaCertFile, err := os.ReadFile(opts.HTTPClientTLSRootCAFile)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to read TLS root CA file %s - %s\",\n\t\t\t\topts.HTTPClientTLSRootCAFile, err)\n\t\t}\n\t\tif !tlsCertPool.AppendCertsFromPEM(caCertFile) {\n\t\t\treturn nil, fmt.Errorf(\"failed to AppendCertsFromPEM %s\", opts.HTTPClientTLSRootCAFile)\n\t\t}\n\t\tn.httpClientTLSConfig.RootCAs = tlsCertPool\n\t}\n\n\tfor _, address := range opts.NSQLookupdHTTPAddresses {\n\t\t_, err := net.ResolveTCPAddr(\"tcp\", address)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to resolve --lookupd-http-address (%s) - %s\", address, err)\n\t\t}\n\t}\n\n\tfor _, address := range opts.NSQDHTTPAddresses {\n\t\t_, err := net.ResolveTCPAddr(\"tcp\", address)\n\t\tif err != nil {","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/nsqio/nsq/blob/85cf10c09c6c3c86160d6f0eb156f62d0efc1648/nsqadmin/nsqadmin.go#L57-L93","documentation":"nsqadmin's New reads --http-client-tls-root-ca-file with os.ReadFile when the flag is non-empty, to build the RootCAs pool used for outbound HTTPS to nsqd/nsqlookupd. If the read fails, startup aborts with 'failed to read TLS root CA file %s - %s' including the underlying os error, which tells you whether it was missing (no such file), unreadable (permission denied), or e.g. a directory. Note this is a plain file read — a parse failure later produces the separate 'failed to AppendCertsFromPEM' error.","triggerScenarios":"Pointing --http-client-tls-root-ca-file at a path that does not exist on the nsqadmin host, a file without read permission for the nsqadmin user, or a path that is a directory (e.g. trailing slash in a template). Distinct from a bad-PEM error: this fires before parsing, purely on os.ReadFile.","commonSituations":"Container images missing the mounted CA volume; paths written for a different host in Ansible/Chef; SELinux denying reads of custom CA locations; a typo'd absolute path; the file existing only on the nsqd nodes, not where nsqadmin runs.","solutions":["Check existence and readability as the nsqadmin user: 'sudo -u nsqadmin test -r /path/ca.pem && echo ok'.","Fix the path/permissions (or mount the secret) and confirm with 'ls -l /path/ca.pem'.","If the target uses a private CA, ensure that CA's PEM was actually copied to this host — node certs are not enough.","Restart nsqadmin; read success moves you past this error."],"exampleFix":"# before\nnsqadmin --http-client-tls-root-ca-file=/etc/nsq/tls/root-ca.pem\n# failed to read TLS root CA file /etc/nsq/tls/root-ca.pem - open ...: no such file or directory\n\n# after\nsudo install -m 0644 ca/root-ca.pem /etc/nsq/tls/root-ca.pem\nsudo -u nsqadmin test -r /etc/nsq/tls/root-ca.pem && echo readable\nnsqadmin --http-client-tls-root-ca-file=/etc/nsq/tls/root-ca.pem","handlingStrategy":"validation","validationCode":"// pre-start: readability check as the service user\nfi, err := os.Stat(path)\nif err != nil || fi.IsDir() || fi.Mode().Perm()&0o400 == 0 {\n    return fmt.Errorf(\"CA file %s missing, a directory, or unreadable\", path)\n}","typeGuard":null,"tryCatchPattern":"if err := startNsqadmin(cfg); err != nil && strings.Contains(err.Error(), \"failed to read TLS root CA file\") {\n    return fmt.Errorf(\"fix path/permissions on %s (mount, chmod, SELinux) then restart\", cfg.HTTPClientTLSRootCAFile)\n}","preventionTips":["Mount CA secrets read-only and verify presence in an initContainer.","Test file readability as the daemon user in deploy scripts.","Keep TLS material paths identical across hosts via config management."],"tags":["tls","filesystem","nsqadmin","configuration","startup","permissions"],"backgroundTag":null,"analyzedSha":"85cf10c09c6c3c86160d6f0eb156f62d0efc1648","analyzedAt":"2026-08-16T00:53:05.009Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}