failed to initialize HTTP server TLS configuration: %s

Error message

failed to initialize HTTP server TLS configuration: %s

What it means

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.

Source

Thrown at command/agent/http.go:149

	handshakeTimeout, err := time.ParseDuration(config.Limits.HTTPSHandshakeTimeout)
	if err != nil {
		return srvs, fmt.Errorf("error parsing https_handshake_timeout: %v", err)
	} else if handshakeTimeout < 0 {
		return srvs, fmt.Errorf("https_handshake_timeout must be >= 0")
	}

	// Get max connection limit
	maxConns := 0
	if mc := config.Limits.HTTPMaxConnsPerClient; mc != nil {
		maxConns = *mc
	}
	if maxConns < 0 {
		return srvs, fmt.Errorf("http_max_conns_per_client must be >= 0")
	}

	tlsConf, err := tlsutil.NewTLSConfiguration(config.TLSConfig, config.TLSConfig.VerifyHTTPSClient, true)
	if err != nil && config.TLSConfig.EnableHTTP {
		return srvs, fmt.Errorf("failed to initialize HTTP server TLS configuration: %s", err)
	}

	wsUpgrader := &websocket.Upgrader{
		ReadBufferSize:  2048,
		WriteBufferSize: 2048,
		Subprotocols:    []string{websocketProtocolWatcher},
	}

	// If running in dev mode and the option to disable the websocket origin check is unset
	// then disable the origin check. Otherwise, only disable if it has been explicitly set
	// in the configuration. Disabling of the origin check is useful when doing UI development
	// and using the ember proxy to reach an agent in dev mode or a local cluster.
	if (config.DevMode && config.HTTPDisableWebSocketOriginCheck == nil) ||
		(config.HTTPDisableWebSocketOriginCheck != nil && *config.HTTPDisableWebSocketOriginCheck) {
		wsUpgrader.CheckOrigin = func(*http.Request) bool {
			return true
		}
	}

View on GitHub (pinned to 482b49bf1a)

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.

Example fix

// before (HCL)
tls {
  http = true
  cert_file = "/etc/nomad/server.pem"
  key_file  = "/etc/nomad/server.key.pem"
}
// after (correct, readable, matching pair)
tls {
  http = true
  ca_file   = "/etc/nomad/ca.pem"
  cert_file = "/etc/nomad/server.pem"
  key_file  = "/etc/nomad/server-key.pem"
}

Defensive patterns

Strategy: validation

Validate before calling

for _, p := range []string{tlsCfg.CertFile, tlsCfg.KeyFile, tlsCfg.CAFile} {
    if p != "" {
        if _, err := os.Stat(p); err != nil {
            return fmt.Errorf("tls file unreadable: %s: %v", p, err)
        }
    }
}

Try / catch

if err := agent.Setup(); err != nil {
    if strings.Contains(err.Error(), "failed to initialize HTTP server TLS configuration") {
        // inspect wrapped error: fix cert/key/CA paths or reissue the pair
    }
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

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

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/32c011515733f8cd. Report an issue: GitHub.