hashicorp/nomad · error

check %q is missing a port

Error message

check %q is missing a port

What it means

A check that requires a port (RequiresPort, e.g. tcp/http checks) ended up with an empty effective port: neither the check's own port field nor the parent service's port label supplied one. Nomad derives the effective port from the check first, then inherits the service PortLabel, and errors when both are empty.

Source

Thrown at nomad/structs/structs.go:8546

			}

			if check.AddressMode == AddressModeAllocIPv6 {
				mErr.Errors = append(mErr.Errors, fmt.Errorf("check %q cannot use address_mode=\"alloc_ipv6\", only checks defined in a \"group\" service block can use this mode", service.Name))
			}

			if !check.RequiresPort() {
				// No need to continue validating check if it doesn't need a port
				continue
			}

			effectivePort := check.PortLabel
			if effectivePort == "" {
				// 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 {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add `port = "<label>"` to the check block referencing a group network port label.
2. Ensure the parent service has a valid port_label the check can inherit.
3. If the check genuinely needs no port (e.g. some script checks), switch the check type to one where RequiresPort() is false.
4. Run `nomad job validate` to catch missing ports pre-submit.

Example fix

// before
service {
  name = "api"
  port = "http"
  check { name = "live"; type = "http"; path = "/health" }
}

// after
service {
  name = "api"
  port = "http"
  check { name = "live"; type = "http"; path = "/health"; port = "http" }
}

for _, svc := range allServices {
  for _, c := range svc.Checks {
    if c.RequiresPort() && c.Port == "" && svc.PortLabel == "" {
      return fmt.Errorf("service %q: check %q has no port and service has no port_label", svc.Name, c.Name)
    }
  }
}

When it happens

Trigger: Submitting a job where a check of a port-requiring type (tcp/http) omits its `port` while the parent service has an empty port_label (e.g. address_mode="driver" with a numeric service port); check.RequiresPort() returns true and effectivePort resolves to "".

Common situations: Using a numeric port on the service without a labeled port so the check cannot inherit a label; forgetting the check `port` attribute when the service declares one; script/grpc-less check types misconfigured without ports.

Related errors

• check %q is duplicate
• check %q cannot use address_mode="alloc", only checks define
• check %q has invalid numeric port %d
• check %q cannot use a numeric port %d without setting addres
• error parsing port %q from service %q: %v

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