hashicorp/nomad · error

http_max_conns_per_client must be >= 0

Error message

http_max_conns_per_client must be >= 0

What it means

Returned by NewHTTPServers (command/agent/http.go:144) when `limits.http_max_conns_per_client` is set to a negative integer. The per-client HTTP connection cap must be zero or positive (0 meaning unlimited), so a negative value aborts HTTP server startup.

Source

Thrown at command/agent/http.go:144

		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)
	}

	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) ||

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set http_max_conns_per_client to 0 for unlimited or a positive integer for a cap.
2. Remove the setting entirely to accept defaults.
3. Fix automation that substitutes -1 as an unset sentinel.
4. Run `nomad validate` before deploying the config.

Example fix

// before (HCL)
limits {
  http_max_conns_per_client = -1
}
// after
limits {
  http_max_conns_per_client = 0
}

if mc := cfg.Limits.HTTPMaxConnsPerClient; mc != nil && *mc < 0 {
    return fmt.Errorf("http_max_conns_per_client must be >= 0")
}

func validMaxConns(v *int) bool {
    return v == nil || *v >= 0
}

if err != nil {
    if strings.Contains(err.Error(), "http_max_conns_per_client must be >= 0") {
        // set to 0 (unlimited) or a positive cap and re-run setup
    }
}

When it happens

Trigger: Configuring `limits { http_max_conns_per_client = -1 }` — the '-1 means unlimited' idiom from other software — and starting or reloading the Nomad agent.

Common situations: Carrying over -1 = unlimited conventions from nginx etc.; automation scripts substituting -1 as an 'unset' sentinel; sign typos when hand-editing config.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Reschedule policy has unlimited attempts enabled and a low d
• Lock delay and TTL must be positive
• rpc_max_conns_per_client must be > %d; found: %d
• https_handshake_timeout must be >= 0
• server_join and retry_join cannot both be defined; prefer se

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