hashicorp/nomad · error

Failed to parse RPC address %q: %v

Error message

Failed to parse RPC address %q: %v

What it means

convertServerConfig resolves the normalized RPC bind address with net.ResolveTCPAddr; failure means the configured bind address (bad host/IP syntax or unresolvable name) cannot be used for the server's RPC listener, aborting startup.

Source

Thrown at command/agent/agent.go:398

		if jobMaxCount < 0 {
			return nil, fmt.Errorf("job_max_count (%d) cannot be negative", jobMaxCount)
		}
	}
	conf.JobMaxCount = jobMaxCount

	if agentConfig.Server.JobTrackedVersions != nil {
		if *agentConfig.Server.JobTrackedVersions <= 0 {
			return nil, fmt.Errorf("job_tracked_versions must be greater than 0")
		}
		conf.JobTrackedVersions = *agentConfig.Server.JobTrackedVersions
	}

	conf.OIDCIssuer = agentConfig.Server.OIDCIssuer

	// Set up the bind addresses
	rpcAddr, err := net.ResolveTCPAddr("tcp", agentConfig.normalizedAddrs.RPC)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse RPC address %q: %v", agentConfig.normalizedAddrs.RPC, err)
	}
	serfAddr, err := net.ResolveTCPAddr("tcp", agentConfig.normalizedAddrs.Serf)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse Serf address %q: %v", agentConfig.normalizedAddrs.Serf, err)
	}
	conf.RPCAddr.Port = rpcAddr.Port
	conf.RPCAddr.IP = rpcAddr.IP
	conf.SerfConfig.MemberlistConfig.BindPort = serfAddr.Port
	conf.SerfConfig.MemberlistConfig.BindAddr = serfAddr.IP.String()
	conf.SerfConfig.RejoinAfterLeave = agentConfig.Server.RejoinAfterLeave

	// Set up the advertise addresses
	rpcAddr, err = net.ResolveTCPAddr("tcp", agentConfig.AdvertiseAddrs.RPC)
	if err != nil {
		return nil, fmt.Errorf("Failed to parse RPC advertise address %q: %v", agentConfig.AdvertiseAddrs.RPC, err)
	}
	serfAddr, err = net.ResolveTCPAddr("tcp", agentConfig.AdvertiseAddrs.Serf)
	if err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the bind_addr/RPC address in the server config to a valid IP:port or resolvable host
2. Check DNS resolution for hostname-based bind addresses

When it happens

Trigger: Thrown at command/agent/agent.go:398 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/3f125a818d70fe8b. Report an issue: GitHub.