hashicorp/nomad · error

Task group network validation failed: %v

Error message

Task group network validation failed: %v

What it means

TaskGroup.Validate calls tg.validateNetworks() and, if it fails, wraps the underlying error as "Task group network validation failed: %v" before appending it to the job multierror. It indicates invalid network resource configuration at the group or task level (e.g. conflicting port labels, illegal static/dynamic port mixes, bridge/hostname mode constraints).

Source

Thrown at nomad/structs/structs.go:7294

	if len(tg.Tasks) > 0 && mainTasks == 0 {
		mErr = multierror.Append(mErr, fmt.Errorf("Task group %s must have at least one main task", tg.Name))
	}

	// Validate the volume requests
	var canaries int
	if tg.Update != nil {
		canaries = tg.Update.Canary
	}
	for name, volReq := range tg.Volumes {
		if err := volReq.Validate(j.Type, tg.Count, canaries); err != nil {
			mErr = multierror.Append(mErr, fmt.Errorf(
				"Task group volume validation for %s failed: %v", name, err))
		}
	}

	// Validate task group and task network resources
	if err := tg.validateNetworks(); err != nil {
		outer := fmt.Errorf("Task group network validation failed: %v", err)
		mErr = multierror.Append(mErr, outer)
	}

	// Validate task group and task services
	if err := tg.validateServices(); err != nil {
		outer := fmt.Errorf("Task group service validation failed: %v", err)
		mErr = multierror.Append(mErr, outer)
	}

	// Validate group service script-checks
	if err := tg.validateScriptChecksInGroupServices(); err != nil {
		outer := fmt.Errorf("Task group service check validation failed: %v", err)
		mErr = multierror.Append(mErr, outer)
	}

	// Validate the scaling policy
	if err := tg.validateScalingPolicy(j); err != nil {
		outer := fmt.Errorf("Task group scaling policy validation failed: %v", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped inner error and correct the offending network/port field in the group.
2. Ensure port labels are unique within the group and static ports are within the client's allowed range.
3. Verify the target client supports the requested network mode (bridge/cni plugin installed).

Example fix

// before
network {
  port "http" { static = 8080 }
  port "http" { to = 8081 }
}
// after
network {
  port "http" { to = 8080 }
  port "metrics" { to = 8081 }
}

// Go: check for duplicate port labels in group networks
labels := map[string]bool{}
for _, n := range tg.Networks {
  for _, p := range n.DynamicPorts {
    if labels[p.Label] {
      return fmt.Errorf("duplicate port label %q", p.Label)
    }
    labels[p.Label] = true
  }
}

When it happens

Trigger: Submitting a job whose `network` stanza (group-level or legacy task-level) fails inner validation — duplicate port labels, reserved ports out of range, network mode unsupported, hostname collisions across tasks.

Common situations: Two tasks in a group declaring the same port label; static port conflicts between groups; using `mode = "bridge"` on clients without CNI; copying old task-level network stanzas into groups.

Related errors

• Port label %s already in use by %s
• ErrConnectRequireOneNetwork
• %s: %w: group %q has %d networks
• error parsing reserved_ports: %w
• error parsing reserved_ports for network %q: %w

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