hashicorp/nomad · error

consul address for cluster %q must be set on nomad client

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.

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)

Solutions

1. Set consul.addresses/<cluster>.grpc_http or grpc address in client config
2. Verify the client's Consul cluster configuration block name matches the one referenced by the services
3. Restart the Nomad client after fixing the config

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.