{"record":{"id":"057252dfa8b61bce","repo":"hashicorp/nomad","slug":"failed-to-start-workers-v","errorCode":null,"errorMessage":"Failed to start workers: %v","messagePattern":"Failed to start workers: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/server.go","lineNumber":506,"sourceCode":"\tif err := s.setupRaft(); err != nil {\n\t\ts.Shutdown()\n\t\ts.logger.Error(\"failed to start Raft\", \"error\", err)\n\t\treturn nil, fmt.Errorf(\"Failed to start Raft: %v\", err)\n\t}\n\n\t// Initialize the wan Serf\n\ts.serf, err = s.setupSerf(config.SerfConfig, s.eventCh, serfSnapshot)\n\tif err != nil {\n\t\ts.Shutdown()\n\t\ts.logger.Error(\"failed to start serf WAN\", \"error\", err)\n\t\treturn nil, fmt.Errorf(\"Failed to start serf: %v\", err)\n\t}\n\n\t// Initialize the scheduling workers\n\tif err := s.setupWorkers(s.shutdownCtx); err != nil {\n\t\ts.Shutdown()\n\t\ts.logger.Error(\"failed to start workers\", \"error\", err)\n\t\treturn nil, fmt.Errorf(\"Failed to start workers: %v\", err)\n\t}\n\n\t// Setup the Consul syncer\n\tif err := s.setupConsulSyncer(); err != nil {\n\t\ts.logger.Error(\"failed to create server consul syncer\", \"error\", err)\n\t\treturn nil, fmt.Errorf(\"failed to create server Consul syncer: %v\", err)\n\t}\n\n\t// Setup the deployment watcher.\n\tif err := s.setupDeploymentWatcher(); err != nil {\n\t\ts.logger.Error(\"failed to create deployment watcher\", \"error\", err)\n\t\treturn nil, fmt.Errorf(\"failed to create deployment watcher: %v\", err)\n\t}\n\n\t// Setup the volume watcher\n\tif err := s.setupVolumeWatcher(); err != nil {\n\t\ts.logger.Error(\"failed to create volume watcher\", \"error\", err)\n\t\treturn nil, fmt.Errorf(\"failed to create volume watcher: %v\", err)","sourceCodeStart":488,"sourceCodeEnd":524,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/server.go#L488-L524","documentation":"After Raft and Serf come up, NewServer starts the scheduling workers via setupWorkers(s.shutdownCtx). Any failure there (worker/eval broker initialization) shuts the server down and returns \"Failed to start workers: %v\". This is rare and usually reflects an internal configuration or resource problem rather than external state.","triggerScenarios":"Starting a server where setupWorkers fails — e.g. invalid worker-related server configuration producing a bad scheduler config, or context/resource initialization errors while creating the eval broker and worker goroutines.","commonSituations":"Custom builds or enterprise/oss scheduler mismatches; extremely constrained environments; misconfigured server config that reaches worker setup with invalid values; regression after upgrading with modified defaults.","solutions":["Read the wrapped cause from the server log (\"failed to start workers\") and fix the named configuration problem","Remove unusual scheduler/worker overrides in the server config and retry with defaults","Confirm the binary matches the intended edition (OSS vs Enterprise) and version consistency across config","If persistent, file an issue with the underlying error since this indicates an unexpected internal failure"],"exampleFix":"// before\nserver {\n  default_scheduler_config = \"bogus\"\n}\n// after\nserver { enabled = true } # worker/scheduler settings at defaults","handlingStrategy":"try-catch","validationCode":"// Validate server config defaults before startup in embedders\nif cfg.DefaultSchedulerConfig != (structs.SchedulerConfiguration{}) {\n    // ensure values are ones your build supports\n}","typeGuard":null,"tryCatchPattern":"srv, err := nomad.NewServer(config, catalog, consulFn)\nif err != nil {\n    if strings.Contains(err.Error(), \"Failed to start workers\") {\n        log.Printf(\"worker init failed, retry with default server config: %v\", err)\n    }\n    return err\n}","preventionTips":["Run servers with default worker/scheduler settings unless a specific override is required","Match OSS vs Enterprise binary to your config options","Capture the underlying 'failed to start workers' log line for bug reports"],"tags":["nomad","go","workers","scheduler","startup"],"backgroundTag":"server-startup-failed","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"}