hashicorp/nomad · error

Port %s (%d) cannot be greater than %d

Error message

Port %s (%d) cannot be greater than %d

What it means

In TaskGroup network port validation, a static port value exceeded 65535 (math.MaxUint16), which cannot be represented as a valid port; the label and offending value are included in the message.

Source

Thrown at nomad/structs/structs.go:7358

			}

			if port.Value != 0 {
				hostNetwork := port.HostNetwork
				if hostNetwork == "" {
					hostNetwork = "default"
				}
				staticPorts, ok := staticPortsIndex[hostNetwork]
				if !ok {
					staticPorts = make(map[int]string)
				}
				// static port
				if other, ok := staticPorts[port.Value]; ok {
					if !port.IgnoreCollision {
						err := fmt.Errorf("Static port %d already reserved by %s", port.Value, other)
						mErr.Errors = append(mErr.Errors, err)
					}
				} else if port.Value > math.MaxUint16 {
					err := fmt.Errorf("Port %s (%d) cannot be greater than %d", port.Label, port.Value, math.MaxUint16)
					mErr.Errors = append(mErr.Errors, err)
				} else {
					staticPorts[port.Value] = fmt.Sprintf("taskgroup network:%s", port.Label)
					staticPortsIndex[hostNetwork] = staticPorts
				}
			}

			if port.To < -1 {
				err := fmt.Errorf("Port %q cannot be mapped to negative value %d", port.Label, port.To)
				mErr.Errors = append(mErr.Errors, err)
			} else if port.To > math.MaxUint16 {
				err := fmt.Errorf("Port %q cannot be mapped to a port (%d) greater than %d", port.Label, port.To, math.MaxUint16)
				mErr.Errors = append(mErr.Errors, err)
			}

			if port.IgnoreCollision && !(net.Mode == "" || net.Mode == "host") {
				err := fmt.Errorf("Port %q collision may not be ignored on non-host network mode %q", port.Label, net.Mode)
				mErr.Errors = append(mErr.Errors, err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct the static value to <= 65535
2. If the intended container-side port exceeds 65535, that's invalid — use a valid port
3. Use a dynamic port (omit static value) if you don't need a fixed host port
4. Add pre-submit validation in tooling that generates job specs to clamp/check port ranges

Example fix

// before
network {
  port "web" { static = 655360 }
}
// after
network {
  port "web" { static = 8080 }
}

const maxPort = 65535
func portsInRange(tg *api.TaskGroup) error {
  for _, n := range tg.Networks {
    for _, p := range append(n.ReservedPorts, n.DynamicPorts...) {
      if p.Value < 0 || p.Value > maxPort { return fmt.Errorf("port %q value %d out of range", p.Label, p.Value) }
      if p.To > maxPort { return fmt.Errorf("port %q 'to' %d out of range", p.Label, p.To) }
    }
  }
  return nil
}

When it happens

Trigger: Declaring a network port with `static = <n>` where n > 65535 (or ReservedPorts.Value > 65535) in a task group network block — often from unit confusion (e.g. typo'd digits) or programmatic spec generation.

Common situations: Copy/paste mistakes like static = 655360; scripts computing ports from offsets that overflow; confusing `to` (container port, also uint16-bounded) values; JSON job specs with unvalidated user input.

Related errors

• error parsing reserved_ports: %w
• error parsing reserved_ports for network %q: %w
• Task group network validation failed: %v
• Port label %s already in use by %s
• Static port %d already reserved by %s

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