hashicorp/nomad · error

invalid port: %q: not a valid port mapping or numeric port

Error message

invalid port: %q: not a valid port mapping or numeric port

What it means

In GetAddress under AddressModeAuto, the port label is neither a known port mapping (ports.Get) nor parseable as a numeric port, so no address/port pair can be produced for the service or check registration. Indicates a typo or missing port label in the job spec.

Source

Thrown at client/serviceregistration/address.go:44

) (string, int, error) {
	switch addressMode {
	case structs.AddressModeAuto:
		switch {
		case address != "":
			// No port no problem, just return the advertise address.
			if portLabel == "" {
				return address, 0, nil
			}
			// A custom advertise address can be used with a port map; using the
			// Value and ignoring the IP. The routing from your custom address to
			// the group network address is DIY. (e.g. EC2 public address)
			if mapping, exists := ports.Get(portLabel); exists {
				return address, mapping.Value, nil
			}
			// If not a port map we can interpolate a numeric port for you.
			port, err := strconv.Atoi(portLabel)
			if err != nil {
				return "", 0, fmt.Errorf("invalid port: %q: not a valid port mapping or numeric port", portLabel)
			}
			return address, port, nil
		case driverNet.Advertise():
			return GetAddress("", structs.AddressModeDriver, portLabel, networks, driverNet, ports, netStatus)
		default:
			return GetAddress("", structs.AddressModeHost, portLabel, networks, driverNet, ports, netStatus)
		}
	case structs.AddressModeHost:
		// Cannot use address mode host with custom advertise address.
		if address != "" {
			return "", 0, fmt.Errorf("cannot use custom advertise address with %q address mode", structs.AddressModeHost)
		}

		if portLabel == "" {
			if len(networks) != 1 {
				// If no networks are specified return zero
				// values. Consul will advertise the host IP
				// with no port. This is the pre-0.7.1 behavior

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Define the port label in the group's network/port block
2. Use a numeric port literal instead of a label
3. Fix the label spelling in the service/check definition

When it happens

Trigger: Thrown at client/serviceregistration/address.go:44 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/4488a3822b7a7e9e. Report an issue: GitHub.