{"record":{"id":"cce54d996e809e05","repo":"hashicorp/nomad","slug":"failed-to-create-server-consul-syncer-v","errorCode":null,"errorMessage":"failed to create server Consul syncer: %v","messagePattern":"failed to create server Consul syncer: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nomad/server.go","lineNumber":512,"sourceCode":"\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)\n\t}\n\ts.volumeControllerFutures = map[string]context.Context{}\n\n\t// Start the eval broker notification system so any subscribers can get\n\t// updates when the processes SetEnabled is triggered.\n\tgo s.evalBroker.enabledNotifier.Run()","sourceCodeStart":494,"sourceCodeEnd":530,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/server.go#L494-L530","documentation":"NewServer wraps any error returned by setupConsulSyncer, which builds the Consul-backed syncer used to advertise and discover Nomad servers and services. The wrapped error indicates the Consul syncer infrastructure could not be initialized, so the server cannot start. It is a startup-only failure: NewServer returns nil and the process should not continue.","triggerScenarios":"NewServer called with a config whose Consul block points to an unreachable/misconfigured Consul agent; setupConsulSyncer fails to create the Consul client (bad address, invalid ACL token, bad TLS/CA settings) or its API client cannot be constructed.","commonSituations":"Bad consul.address in server config, Consul not running in the dev/VM, invalid consul CA cert or ACL token after a credential rotation, malformed auto-join/advertise-retry settings, or server.startup_timeout issues in containerized environments where Consul starts after Nomad.","solutions":["Check the wrapped inner error in the log line just above ('failed to create server consul syncer') to see the root cause.","Verify the Consul agent address is reachable (e.g. `consul members` / curl http://127.0.0.1:8500/v1/agent/self).","Fix consul block in server config: address, ACL token, CA cert, cert/key paths.","Ensure Consul starts before Nomad (systemd dependency or container ordering)."],"exampleFix":"// before\nconsul {\n  address = \"consul.internal:8500\"\n  ca_file = \"/etc/consul/wrong-ca.pem\"\n}\n// after\nconsul {\n  address = \"127.0.0.1:8500\"\n  ca_file = \"/etc/consul/ca.pem\"\n  token   = \"<valid-acl-token>\"\n}","handlingStrategy":"validation","validationCode":"// before NewServer\ndial, err := net.DialTimeout(\"tcp\", cfg.ConsulConfig.ServerAutoJoin != \"\" ? consulAddr : consulAddr, 2*time.Second)\nif err != nil { return fmt.Errorf(\"consul unreachable: %w\", err) }","typeGuard":null,"tryCatchPattern":"srv, err := nomad.NewServer(cfg, logger)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to create server Consul syncer\") {\n        // surface consul connectivity/config remediation\n        return fmt.Errorf(\"server startup blocked: consul syncer init failed: %w\", err)\n    }\n    return err\n}","preventionTips":["Health-check the Consul agent before starting Nomad servers (systemd After=consul.service).","Validate consul address/token/TLS in a preflight script.","Monitor the inner log line 'failed to create server consul syncer' in startup dashboards."],"tags":["startup","consul","configuration"],"backgroundTag":"consul-syncer-init-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"}