hashicorp/nomad · error

invalid port: %q: port must be >0

Error message

invalid port: %q: port must be >0

What it means

Returned by GetAddress when a port label resolves to no allocated or network port and cannot be parsed as a positive integer literal. The label is neither known nor numeric, so no host port can be determined for service registration.

Source

Thrown at client/serviceregistration/address.go:88

		// 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
		if driverNet == nil {
			return "", 0, fmt.Errorf(`cannot use address_mode="driver": no driver network exists`)
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use a port number > 0 in the service/check port field
2. Fix interpolation producing 0 (e.g. missing NOMAD_PORT_ env)

When it happens

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