hashicorp/nomad · error

maximum of %d ports can be reserved

Error message

maximum of %d ports can be reserved

What it means

ParsePortRanges parses a comma-separated port list/range spec (e.g. "80,100-120") for dynamic port reservations. While accumulating individual ports it refuses once the total count exceeds MaxValidPort, so callers cannot reserve an unbounded number of ports in one spec.

Source

Thrown at nomad/structs/funcs.go:522

		l := len(rangeParts)
		switch l {
		case 1:
			if val := rangeParts[0]; val == "" {
				return nil, fmt.Errorf("can't specify empty port")
			} else {
				port, err := strconv.ParseUint(val, 10, 0)
				if err != nil {
					return nil, err
				}
				if port == 0 {
					return nil, fmt.Errorf("port must be > 0")
				}
				if port > MaxValidPort {
					return nil, fmt.Errorf("port must be < %d but found %d", MaxValidPort, port)
				}
				count++
				if count > MaxValidPort {
					return nil, fmt.Errorf("maximum of %d ports can be reserved", MaxValidPort)
				}
				ports = append(ports, port)
			}
		case 2:
			// We are parsing a range
			start, err := strconv.ParseUint(rangeParts[0], 10, 0)
			if err != nil {
				return nil, err
			}

			end, err := strconv.ParseUint(rangeParts[1], 10, 0)
			if err != nil {
				return nil, err
			}

			if end < start {
				return nil, fmt.Errorf("invalid range: ending value (%v) less than starting (%v) value", end, start)
			}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Reduce the number of ports in the spec to 65536 or fewer
2. Split the reservation across multiple port blocks or tasks
3. Check for an off-by-one or unit typo that inflated the range

Example fix

// before
ports = "1-65536"
// after
ports = "20000-20100"

func validatePortSpecCount(spec string, max int) error {
  count := 0
  for _, part := range strings.Split(spec, ",") {
    if strings.Count(part, "-") == 1 {
      r := strings.Split(part, "-")
      s, _ := strconv.Atoi(r[0]); e, _ := strconv.Atoi(r[1])
      count += e - s
    } else { count++ }
  }
  if count > max { return fmt.Errorf("spec reserves %d ports, max %d", count, max) }
  return nil
}

ports, err := structs.ParsePortRanges(spec)
if err != nil {
  return fmt.Errorf("invalid port spec %q: %w", spec, err)
}

When it happens

Trigger: Calling ParsePortRanges with a spec whose total number of individual ports (counting every port inside ranges) exceeds MaxValidPort (65536).

Common situations: Typo in a job's port block producing an enormous range like "1-65536" repeatedly, programmatically generated port lists, or accidentally reserving all ports in a range for a single task.

Related errors

• bitmap must be positive size
• can't specify empty port
• port must be > 0
• port must be < %d but found %d
• invalid range: ending value (%v) less than starting (%v) val

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