{"record":{"id":"05653a0f4d83d684","repo":"hashicorp/nomad","slug":"no-default-consul-services-client","errorCode":null,"errorMessage":"no default Consul services client","messagePattern":"no default Consul services client","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/consul/service_client.go","lineNumber":511,"sourceCode":"\tscw.lock.Lock()\n\tdefer scw.lock.Unlock()\n\n\tfor _, serviceClient := range scw.serviceClients {\n\t\t// TODO(tgross): we never return error from ServiceClient.Shutdown, so\n\t\t// there's no point in returning it here either\n\t\t_ = serviceClient.Shutdown()\n\t}\n\n\treturn nil\n}\n\nfunc (scw *ServiceClientWrapper) RegisterAgent(role string, services []*structs.Service) error {\n\tscw.lock.RLock()\n\tdefer scw.lock.RUnlock()\n\n\tserviceClient, ok := scw.serviceClients[structs.ConsulDefaultCluster]\n\tif !ok {\n\t\treturn errors.New(\"no default Consul services client\")\n\t}\n\treturn serviceClient.RegisterAgent(role, services)\n}\n\nfunc (scw *ServiceClientWrapper) RegisterWorkload(workload *serviceregistration.WorkloadServices) error {\n\tscw.lock.RLock()\n\tdefer scw.lock.RUnlock()\n\n\tclusters := scw.clustersInWorkload(workload)\n\tif len(clusters) == 1 {\n\t\treturn scw.serviceClients[clusters[0]].RegisterWorkload(workload)\n\t}\n\n\tworkloadsByCluster := scw.sliceWorkloadsByCluster(workload, clusters)\n\tfor cluster, workload := range workloadsByCluster {\n\t\terr := scw.serviceClients[cluster].RegisterWorkload(workload)\n\t\tif err != nil {\n\t\t\treturn err","sourceCodeStart":493,"sourceCodeEnd":529,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/consul/service_client.go#L493-L529","documentation":"ServiceClientWrapper.RegisterAgent in command/agent/consul/service_client.go looks up the service client for structs.ConsulDefaultCluster in an internal map. If no client has been registered for the default Consul cluster, it fails immediately with this error. It is a wrapper-layer invariant error: the multi-cluster Consul client map was never populated for the default cluster before agent registration was attempted.","triggerScenarios":"Calling RegisterAgent(role, services) (via setupServer/setupClient) when scw.serviceClients lacks the structs.ConsulDefaultCluster entry — i.e. the Consul service client was not initialized/added before the Nomad agent registered its own services.","commonSituations":"Nomad agent config with Consul integration partially disabled or the consul client failing to initialize at startup; race at boot where agent self-registration runs before the default cluster client is added; custom code constructing a ServiceClientWrapper without calling the init/add for the default cluster.","solutions":["Ensure the Consul client for structs.ConsulDefaultCluster is initialized and added to the ServiceClientWrapper before RegisterAgent is called (check startup order in setupServer/setupClient).","Check the Nomad agent logs for earlier Consul client initialization failures (bad consul.address/TLS settings) that prevented the default client from being created.","Verify the agent's `consul` configuration block is valid and Consul connectivity exists at startup.","If embedding Nomad's service_client package, call the constructor that registers the default cluster client rather than building the map manually."],"exampleFix":"// before: wrapper created with no default client\nscw := &ServiceClientWrapper{serviceClients: map[string]ServiceClient{}}\nscw.RegisterAgent(role, services) // panics into error\n// after: register the default cluster client first\nscw.serviceClients[structs.ConsulDefaultCluster] = serviceClient","handlingStrategy":"try-catch","validationCode":"// before agent self-registration, check the wrapper has the default client\nif _, ok := wrapper.HasClient(structs.ConsulDefaultCluster); !ok {\n    return errors.New(\"consul default client not initialized; check consul config\")\n}","typeGuard":null,"tryCatchPattern":"if err := scw.RegisterAgent(role, services); err != nil {\n    if strings.Contains(err.Error(), \"no default Consul services client\") {\n        log.Error(\"Consul client not initialized at startup; verify consul block and init order\")\n        return err\n    }\n    return err\n}","preventionTips":["Initialize the Consul service client before calling setupServer/setupClient self-registration.","Watch startup logs for Consul client init failures and fail fast.","Validate the agent `consul` config block (address, TLS) before starting registration.","In tests, use the constructor that registers the default cluster client."],"tags":["consul","service-registration","initialization"],"backgroundTag":"missing-client-initialization","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"}