{"record":{"id":"88f510aa34ad7bff","repo":"hashicorp/nomad","slug":"server-service-name-must-be-set-when-auto-advertis","errorCode":null,"errorMessage":"server_service_name must be set when auto_advertise is enabled","messagePattern":"server_service_name must be set when auto_advertise is enabled","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/agent.go","lineNumber":550,"sourceCode":"\tif min := agentConfig.Server.MinHeartbeatTTL; min != 0 {\n\t\tconf.MinHeartbeatTTL = min\n\t}\n\tif maxHPS := agentConfig.Server.MaxHeartbeatsPerSecond; maxHPS != 0 {\n\t\tconf.MaxHeartbeatsPerSecond = maxHPS\n\t}\n\tif failoverTTL := agentConfig.Server.FailoverHeartbeatTTL; failoverTTL != 0 {\n\t\tconf.FailoverHeartbeatTTL = failoverTTL\n\t}\n\n\t// Add the Consul and Vault configs\n\tconf.ConsulConfigs = helper.SliceToMap[map[string]*config.ConsulConfig](\n\t\tagentConfig.Consuls,\n\t\tfunc(cfg *config.ConsulConfig) string { return cfg.Name },\n\t)\n\n\tconsul := conf.ConsulConfigs[structs.ConsulDefaultCluster]\n\tif *consul.AutoAdvertise && consul.ServerServiceName == \"\" {\n\t\treturn nil, fmt.Errorf(\"server_service_name must be set when auto_advertise is enabled\")\n\t}\n\n\tconf.VaultConfigs = helper.SliceToMap[map[string]*config.VaultConfig](\n\t\tagentConfig.Vaults,\n\t\tfunc(cfg *config.VaultConfig) string { return cfg.Name },\n\t)\n\n\t// handle system scheduler preemption default\n\tif agentConfig.Server.DefaultSchedulerConfig != nil {\n\t\tconf.DefaultSchedulerConfig = *agentConfig.Server.DefaultSchedulerConfig\n\t}\n\n\t// handle rpc yamux configuration\n\tconf.RPCSessionConfig = yamux.DefaultConfig()\n\tif agentConfig.RPC != nil {\n\t\tif agentConfig.RPC.AcceptBacklog > 0 {\n\t\t\tconf.RPCSessionConfig.AcceptBacklog = agentConfig.RPC.AcceptBacklog\n\t\t}","sourceCodeStart":532,"sourceCodeEnd":568,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L532-L568","documentation":"Nomad's convertServerConfig validates the agent configuration before building the server config. When Consul auto_advertise is enabled, Nomad must know what service name to register the Nomad server under in Consul, so server_service_name (inside the consul block) is mandatory. If it is empty while auto_advertise = true, startup/reload fails with this error.","triggerScenarios":"Running nomad agent -server (or calling convertServerConfig via serverConfig or handleReload) with a consul block that sets auto_advertise = true but leaves server_service_name unset/empty string.","commonSituations":"Minimal hand-written config files where the consul block only sets address and auto_advertise; copied configs from client-only examples (clients don't need server_service_name); upgrading configs across Nomad versions where validation tightened; partial templates that omitted the server stanza's Consul naming fields.","solutions":["Add server_service_name = \"nomad\" (or your custom name) inside the consul block of the server agent config","Set auto_advertise = false if you do not actually need Consul service registration for servers","Check consul > server_service_name is not being overridden to \"\" by a config merge or CLI flag","If loading config via HCL/JSON, verify the field name spelling (server_service_name) so it actually populates ConsulConfig"],"exampleFix":"// before\nconsul {\n  address = \"127.0.0.1:8500\"\n  auto_advertise = true\n}\n// after\nconsul {\n  address = \"127.0.0.1:8500\"\n  auto_advertise = true\n  server_service_name = \"nomad\"\n}","handlingStrategy":"validation","validationCode":"// Go: validate consul config before handing to nomad agent\nfunc validateConsul(cfg ConsulConfig) error {\n    if cfg.AutoAdvertise != nil && *cfg.AutoAdvertise && cfg.ServerServiceName == \"\" {\n        return errors.New(\"consul.server_service_name must be set when auto_advertise is true\")\n    }\n    return nil\n}","typeGuard":"func hasServerServiceName(c *ConsulConfig) bool {\n    return c != nil && c.ServerServiceName != \"\"\n}","tryCatchPattern":null,"preventionTips":["Always include server_service_name = \"nomad\" in consul blocks for server agents","Run config validation (nomad validate / nomad agent -config in CI) before deployment","Keep server and client config templates separate so server-only fields are present"],"tags":["config","consul","startup-validation","nomad"],"backgroundTag":"missing-required-config-field","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"}