{"record":{"id":"32c011515733f8cd","repo":"hashicorp/nomad","slug":"failed-to-initialize-http-server-tls-configuration","errorCode":null,"errorMessage":"failed to initialize HTTP server TLS configuration: %s","messagePattern":"failed to initialize HTTP server TLS configuration: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"command/agent/http.go","lineNumber":149,"sourceCode":"\thandshakeTimeout, err := time.ParseDuration(config.Limits.HTTPSHandshakeTimeout)\n\tif err != nil {\n\t\treturn srvs, fmt.Errorf(\"error parsing https_handshake_timeout: %v\", err)\n\t} else if handshakeTimeout < 0 {\n\t\treturn srvs, fmt.Errorf(\"https_handshake_timeout must be >= 0\")\n\t}\n\n\t// Get max connection limit\n\tmaxConns := 0\n\tif mc := config.Limits.HTTPMaxConnsPerClient; mc != nil {\n\t\tmaxConns = *mc\n\t}\n\tif maxConns < 0 {\n\t\treturn srvs, fmt.Errorf(\"http_max_conns_per_client must be >= 0\")\n\t}\n\n\ttlsConf, err := tlsutil.NewTLSConfiguration(config.TLSConfig, config.TLSConfig.VerifyHTTPSClient, true)\n\tif err != nil && config.TLSConfig.EnableHTTP {\n\t\treturn srvs, fmt.Errorf(\"failed to initialize HTTP server TLS configuration: %s\", err)\n\t}\n\n\twsUpgrader := &websocket.Upgrader{\n\t\tReadBufferSize:  2048,\n\t\tWriteBufferSize: 2048,\n\t\tSubprotocols:    []string{websocketProtocolWatcher},\n\t}\n\n\t// If running in dev mode and the option to disable the websocket origin check is unset\n\t// then disable the origin check. Otherwise, only disable if it has been explicitly set\n\t// in the configuration. Disabling of the origin check is useful when doing UI development\n\t// and using the ember proxy to reach an agent in dev mode or a local cluster.\n\tif (config.DevMode && config.HTTPDisableWebSocketOriginCheck == nil) ||\n\t\t(config.HTTPDisableWebSocketOriginCheck != nil && *config.HTTPDisableWebSocketOriginCheck) {\n\t\twsUpgrader.CheckOrigin = func(*http.Request) bool {\n\t\t\treturn true\n\t\t}\n\t}","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/http.go#L131-L167","documentation":"Returned by NewHTTPServers (command/agent/http.go:149) when tlsutil.NewTLSConfiguration fails while HTTP TLS is enabled (TLSConfig.EnableHTTP). It wraps the underlying certificate/key/CA parsing or loading error from the `tls` stanza and prevents HTTP server startup.","triggerScenarios":"Starting or reloading the agent with `tls { http = true }` where cert, key, or CA files are missing, unreadable, malformed PEM, mismatched (key does not match cert), or otherwise rejected by the TLS configuration builder.","commonSituations":"Wrong paths after moving certs; key encrypted with a passphrase; cert issued by a different CA; permissions blocking the nomad user; half-written cert picked up during reload.","solutions":["Check the `tls` stanza paths (cert, key, ca_file) and confirm the nomad process can read each file.","Verify cert and key match (compare modulus/fingerprint) and re-issue the pair if not.","Validate PEM files with openssl x509 / openssl rsa and re-export if malformed.","Regenerate material via `nomad tls cert create` or your PKI workflow, then restart/reload the agent."],"exampleFix":"// before (HCL)\ntls {\n  http = true\n  cert_file = \"/etc/nomad/server.pem\"\n  key_file  = \"/etc/nomad/server.key.pem\"\n}\n// after (correct, readable, matching pair)\ntls {\n  http = true\n  ca_file   = \"/etc/nomad/ca.pem\"\n  cert_file = \"/etc/nomad/server.pem\"\n  key_file  = \"/etc/nomad/server-key.pem\"\n}","handlingStrategy":"validation","validationCode":"for _, p := range []string{tlsCfg.CertFile, tlsCfg.KeyFile, tlsCfg.CAFile} {\n    if p != \"\" {\n        if _, err := os.Stat(p); err != nil {\n            return fmt.Errorf(\"tls file unreadable: %s: %v\", p, err)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := agent.Setup(); err != nil {\n    if strings.Contains(err.Error(), \"failed to initialize HTTP server TLS configuration\") {\n        // inspect wrapped error: fix cert/key/CA paths or reissue the pair\n    }\n}","preventionTips":["Verify cert/key match (same modulus) after every rotation.","Check file readability by the nomad user and SELinux labels.","Validate PEM files with openssl before deploying.","Use `nomad tls cert create` to generate consistent material."],"tags":["tls","configuration","certificates","nomad"],"backgroundTag":"tls-certificate-error","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}