hashicorp/nomad · error

server_service_name must be set when auto_advertise is enabl

Error message

server_service_name must be set when auto_advertise is enabled

What it means

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.

Source

Thrown at command/agent/agent.go:550

	if min := agentConfig.Server.MinHeartbeatTTL; min != 0 {
		conf.MinHeartbeatTTL = min
	}
	if maxHPS := agentConfig.Server.MaxHeartbeatsPerSecond; maxHPS != 0 {
		conf.MaxHeartbeatsPerSecond = maxHPS
	}
	if failoverTTL := agentConfig.Server.FailoverHeartbeatTTL; failoverTTL != 0 {
		conf.FailoverHeartbeatTTL = failoverTTL
	}

	// Add the Consul and Vault configs
	conf.ConsulConfigs = helper.SliceToMap[map[string]*config.ConsulConfig](
		agentConfig.Consuls,
		func(cfg *config.ConsulConfig) string { return cfg.Name },
	)

	consul := conf.ConsulConfigs[structs.ConsulDefaultCluster]
	if *consul.AutoAdvertise && consul.ServerServiceName == "" {
		return nil, fmt.Errorf("server_service_name must be set when auto_advertise is enabled")
	}

	conf.VaultConfigs = helper.SliceToMap[map[string]*config.VaultConfig](
		agentConfig.Vaults,
		func(cfg *config.VaultConfig) string { return cfg.Name },
	)

	// handle system scheduler preemption default
	if agentConfig.Server.DefaultSchedulerConfig != nil {
		conf.DefaultSchedulerConfig = *agentConfig.Server.DefaultSchedulerConfig
	}

	// handle rpc yamux configuration
	conf.RPCSessionConfig = yamux.DefaultConfig()
	if agentConfig.RPC != nil {
		if agentConfig.RPC.AcceptBacklog > 0 {
			conf.RPCSessionConfig.AcceptBacklog = agentConfig.RPC.AcceptBacklog
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add server_service_name = "nomad" (or your custom name) inside the consul block of the server agent config
2. Set auto_advertise = false if you do not actually need Consul service registration for servers
3. Check consul > server_service_name is not being overridden to "" by a config merge or CLI flag
4. If loading config via HCL/JSON, verify the field name spelling (server_service_name) so it actually populates ConsulConfig

Example fix

// before
consul {
  address = "127.0.0.1:8500"
  auto_advertise = true
}
// after
consul {
  address = "127.0.0.1:8500"
  auto_advertise = true
  server_service_name = "nomad"
}

// Go: validate consul config before handing to nomad agent
func validateConsul(cfg ConsulConfig) error {
    if cfg.AutoAdvertise != nil && *cfg.AutoAdvertise && cfg.ServerServiceName == "" {
        return errors.New("consul.server_service_name must be set when auto_advertise is true")
    }
    return nil
}

func hasServerServiceName(c *ConsulConfig) bool {
    return c != nil && c.ServerServiceName != ""
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• no such consul cluster: %s
• Failed to initialize Consul client: %v
• error parsing rpc_handshake_timeout: %v
• client_service_name must be set when auto_advertise is enabl
• server_join and start_join cannot both be defined; prefer se

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/88f510aa34ad7bff. Report an issue: GitHub.