{"record":{"id":"69eaa3f449a6c5bc","repo":"hashicorp/nomad","slug":"number-of-schedulers-should-be-between-0-and-d","errorCode":null,"errorMessage":"number of schedulers should be between 0 and %d","messagePattern":"number of schedulers should be between 0 and (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/agent.go","lineNumber":731,"sourceCode":"\n\tconf.KEKProviderConfigs = agentConfig.KEKProviders\n\n\tif startTimeout := agentConfig.Server.StartTimeout; startTimeout != \"\" {\n\t\tdur, err := time.ParseDuration(startTimeout)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to parse start_timeout: %v\", err)\n\t\t} else if dur <= time.Duration(0) {\n\t\t\treturn nil, fmt.Errorf(\"start_timeout should be greater than 0s\")\n\t\t}\n\t\tconf.StartTimeout = dur\n\t}\n\n\t// Ensure the passed number of scheduler is between the bounds of zero and\n\t// the number of CPU cores on the machine. The runtime CPU count object is\n\t// populated at process start time, so there is no overhead in calling the\n\t// function compared to saving the value.\n\tif conf.NumSchedulers < 0 || conf.NumSchedulers > runtime.NumCPU() {\n\t\treturn nil, fmt.Errorf(\"number of schedulers should be between 0 and %d\",\n\t\t\truntime.NumCPU())\n\t}\n\n\t// If the operator has specified a client introduction server config block,\n\t// translate this into the internal server configuration object.\n\tif agentConfig.Server.ClientIntroduction != nil {\n\t\tif agentConfig.Server.ClientIntroduction.Enforcement != \"\" {\n\t\t\tconf.NodeIntroductionConfig.Enforcement = agentConfig.Server.ClientIntroduction.Enforcement\n\t\t}\n\t\tif agentConfig.Server.ClientIntroduction.DefaultIdentityTTL > 0 {\n\t\t\tconf.NodeIntroductionConfig.DefaultIdentityTTL = agentConfig.Server.ClientIntroduction.DefaultIdentityTTL\n\t\t}\n\t\tif agentConfig.Server.ClientIntroduction.MaxIdentityTTL > 0 {\n\t\t\tconf.NodeIntroductionConfig.MaxIdentityTTL = agentConfig.Server.ClientIntroduction.MaxIdentityTTL\n\t\t}\n\t}\n\n\tif err := conf.NodeIntroductionConfig.Validate(); err != nil {","sourceCodeStart":713,"sourceCodeEnd":749,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L713-L749","documentation":"convertServerConfig validates that the computed NumSchedulers is between 0 and runtime.NumCPU(). The value comes from server.num_schedulers in the agent config; Nomad enforces an upper bound of one scheduler per CPU core because schedulers are CPU-bound goroutines. Out-of-range values cause configuration to fail before server startup.","triggerScenarios":"Setting server.num_schedulers to a negative number, or to a value greater than the machine's CPU core count (runtime.NumCPU()), during agent start or a config reload.","commonSituations":"Hard-coded num_schedulers from a larger machine copied to a smaller VM/container (e.g. 16 schedulers on a 4-core host); cgroup CPU limits making runtime.NumCPU() smaller than expected; hand-edited negative values.","solutions":["Set server.num_schedulers to a value between 0 and the host CPU count (check with nproc).","Remove num_schedulers to let Nomad auto-size it to the CPU count.","If running in containers, account for cgroup CPU limits and lower the value accordingly."],"exampleFix":"// before\nserver {\n  num_schedulers = 16  # on a 4-core machine\n}\n// after\nserver {\n  num_schedulers = 4\n}","handlingStrategy":"validation","validationCode":"n := runtime.NumCPU()\nif cfg.NumSchedulers < 0 || cfg.NumSchedulers > n {\n  return fmt.Errorf(\"num_schedulers must be between 0 and %d, got %d\", n, cfg.NumSchedulers)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Omit num_schedulers and let Nomad default to the CPU count.","Clamp template-generated values to runtime.NumCPU() at deploy time.","Remember containers may report fewer CPUs than the host; size per environment."],"tags":["config","nomad","schedulers"],"backgroundTag":"config-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"}