hashicorp/nomad · error

invalid port %d (out of range)

Error message

invalid port %d (out of range)

What it means

AssignPorts rejects a port value that falls outside the valid range [0, MaxValidPort) while assigning dynamic or static ports for an allocation's network. The guard prevents an invalid port value from being checked against the used-port bitmap and producing nonsensical reservations. It means the task's port stanza carries a value the scheduler considers out of range.

Source

Thrown at nomad/structs/network.go:487

// AssignTaskNetwork supports the deprecated task.resources.network block.
func (idx *NetworkIndex) AssignPorts(ask *NetworkResource) (AllocatedPorts, error) {
	var offer AllocatedPorts
	var portsInOffer []int

	// index of host network name to slice of reserved ports, used during dynamic port assignment
	reservedIdx := map[string][]Port{}

	for _, port := range ask.ReservedPorts {
		reservedIdx[port.HostNetwork] = append(reservedIdx[port.HostNetwork], port)

		// allocPort is set in the inner for loop if a port mapping can be created
		// if allocPort is still nil after the loop, the port wasn't available for reservation
		var allocPort *AllocatedPortMapping
		var addrErr error
		for _, addr := range idx.HostNetworks[port.HostNetwork] {
			// Guard against invalid port
			if port.Value < 0 || port.Value >= MaxValidPort {
				return nil, fmt.Errorf("invalid port %d (out of range)", port.Value)
			}

			// Check if in use
			if !port.IgnoreCollision {
				used := idx.getUsedPortsFor(addr.Address)
				if used != nil && used.Check(uint(port.Value)) {
					addrErr = fmt.Errorf("reserved port collision %s=%d", port.Label, port.Value)
					continue
				}
			}

			allocPort = &AllocatedPortMapping{
				Label:           port.Label,
				Value:           port.Value,
				To:              port.To,
				HostIP:          addr.Address,
				IgnoreCollision: port.IgnoreCollision,
			}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the job spec so every static port value is within 0-65535 (and below the scheduler's MaxValidPort ceiling), then resubmit
2. Run nomad job validate (or the /v1/validate endpoints) before submitting jobs to catch out-of-range ports
3. Check for arithmetic/template errors generating the port number in your job templating
4. Ensure all clients and servers run compatible Nomad versions so validation and port ceilings agree

Example fix

// before
port "web" { static = 70000 }
// after
port "web" { static = 8080 }

func validateStaticPorts(job *api.Job) error {
	for _, tg := range job.TaskGroups {
		for _, t := range tg.Tasks {
			for _, r := range t.Resources.Networks {
				for _, p := range r.DynamicPorts {
					if p.Value < 0 || p.Value >= 65536 {
						return fmt.Errorf("port %s value %d out of range", p.Label, p.Value)
					}
				}
			}
		}
	}
	return nil
}

err := client.Jobs().Validate(job, nil, nil)
if err != nil {
	// reject/fix job spec before submit; do not attempt scheduling
}

When it happens

Trigger: A job's network port stanza has a static port value that is negative or >= MaxValidPort (e.g. a value above the valid port ceiling) reaching the scheduler during port assignment; the check runs per host network in the allocation loop.

Common situations: Job files with static = 70000+ or other out-of-range literals that skipped client/job validation (e.g. via API submission without Nomad CLI validation); template-generated jobs computing port numbers incorrectly; older clients/versions with different port ceilings.

Related errors

• error parsing reserved_ports: %w
• error parsing reserved_ports for network %q: %w
• envoy must be used as connect sidecar or gateway
• eval broker is enabled; eval broker must be paused to delete
• eval broker is enabled; eval broker must be paused to delete

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