check %q cannot use a numeric port %d without setting addres

Error message

check %q cannot use a numeric port %d without setting address_mode="driver"

What it means

A check whose effective port is numeric (e.g. "8080") but whose address_mode is not "driver" is rejected: in host/alloc modes the port must be a named label that maps to the host network, because a raw number cannot be resolved to an advertised address. The check must either use a label or opt into driver mode.

Source

Thrown at nomad/structs/structs.go:8565

				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()
		for portLabel := range ports {
			portLabels[portLabel] = struct{}{}
		}
	}

	// COMPAT(0.13)

View on GitHub (pinned to 482b49bf1a)

Solutions

Define a named port in the group network block (e.g. port "http" { to = 8080 }) and set check port = "http".
Or set address_mode = "driver" on the check if the raw container port is intended.
Update the parent service port_label if the numeric value is inherited from it.
Run `nomad job validate` to catch label/port mismatches before submission.

Example fix

// before
check { name = "live"; type = "http"; port = "8080" }

// after
check { name = "live"; type = "http"; port = "http" }
# with group:
# network { port "http" {} }

Defensive patterns

Strategy: validation

Validate before calling

if portStr, err := strconv.Atoi(effectivePort); err == nil && c.AddressMode != "driver" {
  return fmt.Errorf("check %q: numeric port %d requires address_mode=driver or a named port label", c.Name, portStr)
}

Prevention

Always use named port labels for checks in host/alloc address modes
Set address_mode="driver" only when raw container ports are intentional
Keep group network port labels as the single source of truth for ports

When it happens

Trigger: Submitting a job where a check's port (own field or inherited service port_label) is a numeric literal while address_mode is unset/default or "host"/"alloc"; isNumeric is true and address_mode != "driver".

Common situations: Writing port = "8080" instead of a named label like port = "http"; migrating from driver-mode configs to host networking; template-generated jobs emitting raw numbers.

Related errors

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