hashicorp/nomad · error

error parsing https_handshake_timeout: %v

Error message

error parsing https_handshake_timeout: %v

What it means

Returned by NewHTTPServers (command/agent/http.go:133) when the agent config `limits.https_handshake_timeout` fails time.ParseDuration. The value must be a Go duration string like "5s" or "500ms"; an unparseable value aborts HTTP server startup or hot reload.

Source

Thrown at command/agent/http.go:133

	logger     log.Logger
	Addr       string

	wsUpgrader *websocket.Upgrader
}

// NewHTTPServers starts an HTTP server for every address.http configured in
// the agent.
func NewHTTPServers(agent *Agent, config *Config) ([]*HTTPServer, error) {
	var (
		srvs                       []*HTTPServer
		serverInitializationErrors error
		connCount                  atomic.Int32
	)

	// Get connection handshake timeout limit
	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)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add a time unit: https_handshake_timeout = "5s".
2. Use only valid Go duration units (ns, us/µs, ms, s, m, h) — "5sec" is invalid.
3. Validate with time.ParseDuration locally or run `nomad validate <config>` before deploy.
4. If a reload triggered it, fix the config and re-run `nomad agent reload` or restart.

Example fix

// before (HCL)
limits {
  https_handshake_timeout = "5"
}
// after
limits {
  https_handshake_timeout = "5s"
}

if _, err := time.ParseDuration(cfg.Limits.HTTPSHandshakeTimeout); err != nil {
    return fmt.Errorf("https_handshake_timeout invalid: %v", err)
}

if err := agent.Setup(); err != nil {
    if strings.Contains(err.Error(), "error parsing https_handshake_timeout") {
        // fix config to a valid Go duration like "5s" and retry startup
    }
}

When it happens

Trigger: Setting `limits { https_handshake_timeout = "5" }` (missing unit), a typo like "5sec", an empty/whitespace string, or programmatically assigning an invalid string to Limits.HTTPSHandshakeTimeout, then starting or reloading the agent.

Common situations: Config assuming unitless seconds; copying values from tools with different duration syntax; env substitution producing empty strings; old configs from software with different parsing rules.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• no CNI network config found
• failed to parse config:
• failed to convert task schema
• dynamic workload users disabled
• <combined HCL diagnostics from str.String()>

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