hashicorp/nomad · error

error parsing Consul address %q: %v

Error message

error parsing Consul address %q: %v

What it means

When no dedicated GRPCAddr is set, the proxy derives one from Addr by replacing the port with 8502; net.SplitHostPort failed on the configured Consul address (malformed host:port), so run aborts with the parse error wrapped.

Source

Thrown at client/allocrunner/consul_grpc_sock_hook.go:258

		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)
		}
		destAddr = ipStr
	}

	socketFile := allocdir.AllocGRPCSocket
	if p.config.Name != structs.ConsulDefaultCluster && p.config.Name != "" {
		socketFile = filepath.Join(allocdir.SharedAllocName, allocdir.TmpDirName,
			"consul_"+p.config.Name+"_grpc.sock")
	}
	hostGRPCSocketPath := filepath.Join(p.allocDir.AllocDirPath(), socketFile)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct the consul address in client config to a valid host:port form
2. Check for missing port or stray characters in the address
3. Set an explicit grpc address to bypass the fallback path

When it happens

Trigger: Thrown at client/allocrunner/consul_grpc_sock_hook.go:258 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/1a9664297b2fe355. Report an issue: GitHub.