hashicorp/nomad · error

check %q has invalid numeric port %d

Error message

check %q has invalid numeric port %d

What it means

When a check's effective port parses as a number and the check uses address_mode="driver", Nomad validates that the numeric port is a positive TCP/UDP port. A value <= 0 fails this range check and produces this error naming the check and the offending number.

Source

Thrown at nomad/structs/structs.go:8559

				// Inherits from service
				effectivePort = service.PortLabel
			}

			if effectivePort == "" {
				mErr.Errors = append(mErr.Errors, fmt.Errorf("check %q is missing a port", check.Name))
				continue
			}

			isNumeric := false
			portNumber, err := strconv.Atoi(effectivePort)
			if err == nil {
				isNumeric = true
			}

			// Numeric ports are fine for address_mode = "driver"
			if check.AddressMode == "driver" && isNumeric {
				if portNumber <= 0 {
					mErr.Errors = append(mErr.Errors, fmt.Errorf("check %q has invalid numeric port %d", check.Name, portNumber))
				}
				continue
			}

			if isNumeric {
				mErr.Errors = append(mErr.Errors, fmt.Errorf(`check %q cannot use a numeric port %d without setting address_mode="driver"`, check.Name, portNumber))
				continue
			}

			// PortLabel must exist, report errors by its parent service
			addServicePort(effectivePort, service.Name)
		}
	}

	// Get the set of group port labels.
	portLabels := make(map[string]struct{})
	if len(tgNetworks) > 0 {
		ports := tgNetworks[0].PortLabels()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the numeric port to a value between 1 and 65535.
2. Replace the numeric literal with a named network port label (preferred).
3. If port 0 was intentional dynamic assignment, use a group network `dynamic` port and reference its label instead.

Example fix

// before
check { name = "tcp"; type = "tcp"; address_mode = "driver"; port = "0" }

// after
check { name = "tcp"; type = "tcp"; address_mode = "driver"; port = "8080" }

n, err := strconv.Atoi(checkPort)
if err == nil && n <= 0 {
  return fmt.Errorf("check %q: numeric port %d must be > 0", c.Name, n)
}

When it happens

Trigger: Submitting a job where a check with address_mode="driver" has a numeric port (via check port or inherited service port) that is zero or negative, e.g. port = "0" or a negative literal.

Common situations: Placeholder port 0 left in generated jobs; arithmetic/templating producing 0 or -1; mistyping a port when bypassing named labels under driver mode.

Related errors

• Check %s invalid: check requires a port but neither check no
• check %q is missing a port
• check %q cannot use a numeric port %d without setting addres
• missing secret ID
• namespace cannot contain template delimiters or parenthesis

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/17e0f742f86c93ce. Report an issue: GitHub.