hashicorp/nomad · error

unable to parse address template %q: %v

Error message

unable to parse address template %q: %v

What it means

Returned by the Consul gRPC socket hook when GRPCAddr is a sockaddr/template string that listenerutil.ParseSingleIPTemplate cannot parse. The template is meant to expand to a single address; anything else is unusable for the unix socket destination.

Source

Thrown at client/allocrunner/consul_grpc_sock_hook.go:265

		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)

	// if the socket already exists we'll try to remove it, but if not then any
	// other errors will bubble up to the caller here or when we try to listen
	_, err := os.Stat(hostGRPCSocketPath)
	if err == nil {
		err := os.Remove(hostGRPCSocketPath)
		if err != nil {
			return fmt.Errorf(

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the sockaddr template in the consul grpc address config
2. Replace the template with a literal IP address
3. Verify node attributes used by the template exist (e.g. cloud metadata)

When it happens

Trigger: Thrown at client/allocrunner/consul_grpc_sock_hook.go:265 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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