can only parse single port numbers or port ranges (ex. 80,10

Error message

can only parse single port numbers or port ranges (ex. 80,100-120,150)

What it means

ParsePortRanges encountered a port spec segment with more than two hyphen-separated parts; only single ports and `start-end` ranges (e.g. 80,100-120,150) are accepted.

Source

Thrown at nomad/structs/funcs.go:559

			// Full range validation is below but prevent creating
			// arbitrarily large arrays here
			if start == 0 {
				return nil, fmt.Errorf("port must be > 0")
			}
			if end > MaxValidPort {
				return nil, fmt.Errorf("port must be < %d but found %d", MaxValidPort, end)
			}
			count += int(end - start)
			if count > MaxValidPort {
				return nil, fmt.Errorf("maximum of %d ports can be reserved", MaxValidPort)
			}
			ports = slices.Grow(ports, int(end-start))
			for i := start; i <= end; i++ {
				ports = append(ports, i)
			}
		default:
			return nil, fmt.Errorf("can only parse single port numbers or port ranges (ex. 80,100-120,150)")
		}
	}

	return ports, nil
}

// ParentIDFromJobID returns the parent job ID of a given dispatch or periodic
// job. Generally you should use the child job's Job.ParentID field instead, but
// this is useful for contexts where the Job struct isn't present.
func ParentIDFromJobID(jobID string) string {
	if strings.Index(jobID, "/") == 0 {
		// do a cheap O(n) check first before we do the more expensive Cut
		// method
		return jobID
	}
	jobID, _, _ = strings.Cut(jobID, DispatchLaunchSuffix)
	jobID, _, _ = strings.Cut(jobID, PeriodicLaunchSuffix)
	return jobID

View on GitHub (pinned to 482b49bf1a)

Solutions

Rewrite the port spec using only single ports and two-value ranges
Check for stray hyphens or malformed segments in the input

Example fix

// before
ports = "80-90-100"
// after
ports = "80-100"

Defensive patterns

Strategy: validation

Validate before calling

for _, part := range strings.Split(spec, ",") {
  n := strings.Count(part, "-")
  if n != 0 && n != 1 {
    return fmt.Errorf("component %q must be a port or start-end range", part)
  }
}

Try / catch

ports, err := structs.ParsePortRanges(spec)
if err != nil && strings.Contains(err.Error(), "can only parse single port") {
  return fmt.Errorf("malformed port component in %q: %w", spec, err)
}

Prevention

Format port specs as N or N-M only
Avoid ad-hoc string building of ranges
Lint job files with regex ^\d+(-\d+)?(,\d+(-\d+)?)*$

When it happens

Trigger: Passing a malformed component like "80-90-100" or "80--100" (three or zero range parts) to ParsePortRanges.

Common situations: Extra dash typos in HCL job files, copy-paste errors, or tooling that joins ranges with the wrong separator.

Related errors

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