hashicorp/nomad · error

invalid port %q: port label not found

Error message

invalid port %q: port label not found

What it means

In GetAddress's default (host) path, the port label is not found in AllocatedPorts or Networks and is not numeric, so the service registration cannot resolve a host port. Typically a missing port label in the network block or a misnamed dynamic port.

Source

Thrown at client/serviceregistration/address.go:85

		}

		// Default path: use host ip:port
		// Try finding port in the AllocatedPorts struct first
		// Check in Networks struct for backwards compatibility if not found
		mapping, ok := ports.Get(portLabel)
		if !ok {
			mapping = networks.Port(portLabel)
			if mapping.Value > 0 {
				return mapping.HostIP, mapping.Value, nil
			}

			// If port isn't a label, try to parse it as a literal port number
			port, err := strconv.Atoi(portLabel)
			if err != nil {
				// Don't include Atoi error message as user likely
				// never intended it to be a numeric and it creates a
				// confusing error message
				return "", 0, fmt.Errorf("invalid port %q: port label not found", portLabel)
			}
			if port <= 0 {
				return "", 0, fmt.Errorf("invalid port: %q: port must be >0", portLabel)
			}

			// A number was given which will use the Consul agent's address and the given port
			// Returning a blank string as an address will use the Consul agent's address
			return "", port, nil
		}
		return mapping.HostIP, mapping.Value, nil

	case structs.AddressModeDriver:
		// Cannot use address mode driver with custom advertise address.
		if address != "" {
			return "", 0, fmt.Errorf("cannot use custom advertise address with %q address mode", structs.AddressModeDriver)
		}

		// Require a driver network if driver address mode is used

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add the port label to the task/group network resources
2. Reference an existing label from the port map
3. Use a numeric port if static

When it happens

Trigger: Thrown at client/serviceregistration/address.go:85 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/6608cfb8b26a9306. Report an issue: GitHub.