hashicorp/nomad · error

client_service_name must be set when auto_advertise is enabl

Error message

client_service_name must be set when auto_advertise is enabled

What it means

convertClientConfig builds Consul configs and checks the default cluster's ConsulConfig: if AutoAdvertise is true, the client must advertise its services under a Consul service name, so ClientServiceName must be non-empty. When auto_advertise is enabled and client_service_name is blank, configuration fails with this message.

Source

Thrown at command/agent/agent.go:1063

	} else if agentConfig.Client.Reserved.Cores != "" {
		cores := idset.Parse[hw.CoreID](agentConfig.Client.Reserved.Cores)
		res.Cpu.ReservedCpuCores = helper.ConvertSlice(
			cores.Slice(),
			func(id hw.CoreID) uint16 { return uint16(id) },
		)
	}

	conf.Version = agentConfig.Version

	// Set the Consul configurations
	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.ClientServiceName == "" {
		return nil, fmt.Errorf("client_service_name must be set when auto_advertise is enabled")
	}

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

	// Set up Telemetry configuration
	conf.StatsCollectionInterval = agentConfig.Telemetry.collectionInterval
	conf.PublishNodeMetrics = agentConfig.Telemetry.PublishNodeMetrics
	conf.PublishAllocationMetrics = agentConfig.Telemetry.PublishAllocationMetrics
	conf.IncludeAllocMetadataInMetrics = agentConfig.Telemetry.IncludeAllocMetadataInMetrics
	conf.AllowedMetadataKeysInMetrics = agentConfig.Telemetry.AllowedMetadataKeysInMetrics
	conf.DisableAllocationHookMetrics = *agentConfig.Telemetry.DisableAllocationHookMetrics

	// Set the TLS related configs
	conf.TLSConfig = agentConfig.TLSConfig

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add client_service_name = "nomad-client" inside the consul block.
2. Or set auto_advertise = false if Consul advertisement is not wanted.
3. Verify the consul block being validated is the default cluster's config.

Example fix

// before
consul {
  auto_advertise = true
}
// after
consul {
  auto_advertise = true
  client_service_name = "nomad-client"
}

if consulCfg.AutoAdvertise != nil && *consulCfg.AutoAdvertise && consulCfg.ClientServiceName == "" {
  return errors.New("consul.client_service_name is required when auto_advertise = true")
}

When it happens

Trigger: A consul { auto_advertise = true } block (default cluster) in the agent config without client_service_name set, evaluated during agent startup or config reload (handleReload).

Common situations: Enabling Consul auto-advertise but forgetting the required client_service_name; minimal config examples omitting it; migrating to multi-cluster consul config where the default cluster entry lost its service name field.

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
• server_service_name must be set when auto_advertise is enabl
• server_join and start_join cannot both be defined; prefer se
• error creating bootstrap configuration for Connect proxy sid

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