hashicorp/nomad · error

Failed to parse RPC address: %v

Error message

Failed to parse RPC address: %v

What it means

During config normalization, Addresses.RPC is passed through normalizeBind together with BindAddr. If the RPC bind address cannot be parsed into a valid IP (invalid literal, bad template output), the agent aborts startup with this error. The wrapped %v carries the root cause from the address parser.

Source

Thrown at command/agent/config.go:2387

func (c *Config) normalizeAddrs() error {
	if c.BindAddr != "" {
		ipStr, err := listenerutil.ParseSingleIPTemplate(c.BindAddr)
		if err != nil {
			return fmt.Errorf("Bind address resolution failed: %v", err)
		}
		c.BindAddr = ipStr
	}
	c.BindAddr = ipaddr.NormalizeAddr(c.BindAddr)

	httpAddrs, err := normalizeMultipleBind(c.Addresses.HTTP, c.BindAddr)
	if err != nil {
		return fmt.Errorf("Failed to parse HTTP address: %v", err)
	}
	c.Addresses.HTTP = strings.Join(httpAddrs, " ")

	addr, err := normalizeBind(c.Addresses.RPC, c.BindAddr)
	if err != nil {
		return fmt.Errorf("Failed to parse RPC address: %v", err)
	}
	c.Addresses.RPC = addr

	addr, err = normalizeBind(c.Addresses.Serf, c.BindAddr)
	if err != nil {
		return fmt.Errorf("Failed to parse Serf address: %v", err)
	}
	c.Addresses.Serf = addr

	c.normalizedAddrs = &NormalizedAddrs{
		RPC:  normalizeAddrWithPort(c.Addresses.RPC, c.Ports.RPC),
		Serf: normalizeAddrWithPort(c.Addresses.Serf, c.Ports.Serf),
	}
	c.normalizedAddrs.HTTP = make([]string, len(httpAddrs))
	for i, addr := range httpAddrs {
		c.normalizedAddrs.HTTP[i] = normalizeAddrWithPort(addr, c.Ports.HTTP)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix addresses.rpc to a bare valid IP or a working interface template
2. Remove any port suffix from the address (ports belong in ports.rpc)
3. Verify the referenced interface exists (ip link / ifconfig)
4. Read the wrapped error detail to identify the exact parse failure

Example fix

// before
addresses { rpc = "10.0.0.5:8300" } // port not allowed
// after
addresses { rpc = "10.0.0.5" }
ports { rpc = 8300 }

func validBindAddr(v string) bool {
	if v == "" { return true }
	return net.ParseIP(v) != nil && !strings.Contains(v, ":8") || net.ParseIP(v) != nil
}
// ensure net.ParseIP(cfg.Addresses.RPC) != nil before deploy

When it happens

Trigger: Configuring addresses.rpc to an unparseable value: malformed IP, a go-sockaddr/template expression that errors, or an empty value where BindAddr itself is also invalid.

Common situations: Copy-pasting an advertise-style 'host:port' into addresses.rpc (port not allowed here); template referencing a nonexistent network interface; IPv6 literal missing brackets or zone.

Understand the failure class

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

Related errors

• Bind address resolution failed: %v
• Failed to parse HTTP address: %v
• Failed to parse Serf address: %v
• No addresses found, please configure one.
• AdvertiseAddrs is nil or empty

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