hashicorp/nomad · error
consul address for cluster
Error message
consul address for cluster %q must be set on nomad client
What it means
Socket-proxy run guard: neither a gRPC address (GRPCAddr) nor a plain HTTP address (Addr) is configured for the named Consul cluster on this Nomad client, so the proxy cannot determine its upstream destination and refuses to start.
Solutions
- Set consul.addresses/<cluster>.grpc_http or grpc address in client config
- Verify the client's Consul cluster configuration block name matches the one referenced by the services
- Restart the Nomad client after fixing the config
Defensive patterns
Strategy: validation
When it happens
Trigger: Thrown at client/allocrunner/consul_grpc_sock_hook.go:247 when the library encounters an invalid state.
Common situations: See trigger scenarios.
AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04).
Data as JSON: /api/errors/4bd93b9470ea5831.
Report an issue: GitHub.
Appendix: source
Thrown at client/allocrunner/consul_grpc_sock_hook.go:247
// Only run once.
if p.runOnce {
return nil
}
// Only run once. Never restart.
select {
case <-p.doneCh:
p.logger.Trace("socket proxy already shutdown; exiting")
return nil
case <-p.ctx.Done():
p.logger.Trace("socket proxy already done; exiting")
return nil
default:
}
// make sure either grpc or http consul address has been configured
if p.config.GRPCAddr == "" && p.config.Addr == "" {
return fmt.Errorf("consul address for cluster %q must be set on nomad client",
p.config.Name)
}
destAddr := p.config.GRPCAddr
if destAddr == "" {
// No GRPCAddr defined. Use Addr but replace port with the gRPC
// default of 8502.
host, _, err := net.SplitHostPort(p.config.Addr)
if err != nil {
return fmt.Errorf("error parsing Consul address %q: %v", p.config.Addr, err)
}
destAddr = net.JoinHostPort(host, p.consulGRPCFallbackPort)
} else {
// GRPCAddr may be sockaddr/template string, parse it.
ipStr, err := listenerutil.ParseSingleIPTemplate(destAddr)
if err != nil {
return fmt.Errorf("unable to parse address template %q: %v", destAddr, err)View on GitHub (pinned to 482b49bf1a)