{"record":{"id":"434173c2e714661a","repo":"hashicorp/nomad","slug":"rpc-max-conns-per-client-must-be-d-found-d","errorCode":null,"errorMessage":"rpc_max_conns_per_client must be > %d; found: %d","messagePattern":"rpc_max_conns_per_client must be > (.+?); found: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/agent.go","lineNumber":609,"sourceCode":"\tconf.DisableDispatchedJobSummaryMetrics = agentConfig.Telemetry.DisableDispatchedJobSummaryMetrics\n\tconf.DisableQuotaUtilizationMetrics = agentConfig.Telemetry.DisableQuotaUtilizationMetrics\n\tconf.DisableRPCRateMetricsLabels = agentConfig.Telemetry.DisableRPCRateMetricsLabels\n\n\tif d, err := time.ParseDuration(agentConfig.Limits.RPCHandshakeTimeout); err != nil {\n\t\treturn nil, fmt.Errorf(\"error parsing rpc_handshake_timeout: %v\", err)\n\t} else if d < 0 {\n\t\treturn nil, fmt.Errorf(\"rpc_handshake_timeout must be >= 0\")\n\t} else {\n\t\tconf.RPCHandshakeTimeout = d\n\t}\n\n\t// Set max rpc conns; nil/0 == unlimited\n\t// Leave a little room for streaming RPCs\n\tminLimit := config.LimitsNonStreamingConnsPerClient + 5\n\tif agentConfig.Limits.RPCMaxConnsPerClient == nil || *agentConfig.Limits.RPCMaxConnsPerClient == 0 {\n\t\tconf.RPCMaxConnsPerClient = 0\n\t} else if limit := *agentConfig.Limits.RPCMaxConnsPerClient; limit <= minLimit {\n\t\treturn nil, fmt.Errorf(\"rpc_max_conns_per_client must be > %d; found: %d\", minLimit, limit)\n\t} else {\n\t\tconf.RPCMaxConnsPerClient = limit\n\t}\n\n\t// Set deployment rate limit\n\tif rate := agentConfig.Server.DeploymentQueryRateLimit; rate == 0 {\n\t\tconf.DeploymentQueryRateLimit = deploymentwatcher.LimitStateQueriesPerSecond\n\t} else if rate > 0 {\n\t\tconf.DeploymentQueryRateLimit = rate\n\t} else {\n\t\treturn nil, fmt.Errorf(\"deploy_query_rate_limit must be greater than 0\")\n\t}\n\n\t// Set plan rejection tracker configuration.\n\tif planRejectConf := agentConfig.Server.PlanRejectionTracker; planRejectConf != nil {\n\t\tif planRejectConf.Enabled != nil {\n\t\t\tconf.NodePlanRejectionEnabled = *planRejectConf.Enabled\n\t\t}","sourceCodeStart":591,"sourceCodeEnd":627,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L591-L627","documentation":"limits.rpc_max_conns_per_client caps non-streaming RPC connections per client. Nomad reserves room for streaming RPCs, so the value must exceed config.LimitsNonStreamingConnsPerClient + 5; a positive value at or below that minimum is rejected at startup/reload. Setting nil or 0 means unlimited and is allowed.","triggerScenarios":"Setting limits { rpc_max_conns_per_client = 10 } (or any small positive number <= minLimit) in a server agent config and starting the agent or reloading config via handleReload.","commonSituations":"Operators aggressively lowering connection limits on small clusters without knowing the internal floor; configs tuned from older versions where the minimum was lower; copy-paste of small round numbers like 5 or 10.","solutions":["Raise rpc_max_conns_per_client above the printed minimum (the error message states the required minLimit value)","Remove the setting or set it to 0 for unlimited connections","Scale down the number of clients instead of the per-client connection cap if resources are constrained","Check the Nomad version's config.LimitsNonStreamingConnsPerClient constant to know the exact floor"],"exampleFix":"// before\nlimits {\n  rpc_max_conns_per_client = 10\n}\n// after\nlimits {\n  rpc_max_conns_per_client = 100\n}","handlingStrategy":"validation","validationCode":"// Go: check the value against the known floor before applying\nconst minLimit = config.LimitsNonStreamingConnsPerClient + 5\nif p := cfg.Limits.RPCMaxConnsPerClient; p != nil && *p != 0 && *p <= minLimit {\n    return fmt.Errorf(\"rpc_max_conns_per_client must be > %d\", minLimit)\n}","typeGuard":"func validMaxConns(p *int) bool {\n    return p == nil || *p == 0 || *p > config.LimitsNonStreamingConnsPerClient+5\n}","tryCatchPattern":null,"preventionTips":["Leave rpc_max_conns_per_client unset unless you have a measured need to cap it","Read the error message: it prints the exact minimum required","Re-check the minimum floor when upgrading Nomad versions"],"tags":["config","validation","limits","nomad"],"backgroundTag":"config-value-out-of-range","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"}