invalid port label %q: port labels in driver address_mode mu

Error message

invalid port label %q: port labels in driver address_mode must be numeric or in the driver's port map

What it means

Returned by GetAddress in driver address_mode when the port label is absent from the driver's port map and is not a numeric literal. Driver-mode addresses must come from the driver network's mapped ports.

Source

Thrown at client/serviceregistration/address.go:129

		}

		// If the port is a label, use the driver's port (not the host's)
		if port, ok := ports.Get(portLabel); ok {
			return driverNet.IP, port.To, nil
		}

		// Check if old style driver portmap is used
		if port, ok := driverNet.PortMap[portLabel]; ok {
			return driverNet.IP, port, 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 label %q: port labels in driver address_mode must be numeric or in the driver's port map", portLabel)
		}
		if port <= 0 {
			return "", 0, fmt.Errorf("invalid port: %q: port must be >0", portLabel)
		}

		return driverNet.IP, port, nil

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

		// Going to need a network for this.
		if netStatus == nil {
			return "", 0, fmt.Errorf(`cannot use address_mode="alloc": no allocation network status reported`)
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

Use a numeric port or a label present in the driver's port map
Define the port in the group network block

Defensive patterns

Strategy: validation

When it happens

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