Port %q collision may not be ignored on non-host network mod

Error message

Port %q collision may not be ignored on non-host network mode %q

What it means

TaskGroup network validation: ignore_collision was set on a port while the network mode is not "host". Port collision ignoring relies on host-network semantics, so it is rejected for bridge and other non-host modes.

Source

Thrown at nomad/structs/structs.go:7375

				} 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)
			}
		}
		// Validate the cniArgs in each network resource. Make sure there are no duplicate Args in
		// different network resources or invalid characters (;) in key or value ;)
		if net.CNI != nil {
			for k, v := range net.CNI.Args {
				if cniArgKeys.Contains(k) {
					err := fmt.Errorf("duplicate CNI arg %q", k)
					mErr.Errors = append(mErr.Errors, err)
				} else {
					cniArgKeys.Insert(k)
				}
				// CNI_ARGS is a ";"-separated string of "key=val", so a ";"
				// in either key or val would confuse plugins (or libraries)
				// that parse that string.
				// Pre-validating this here protects job authors from submitting
				// a job that will most likely error later on the client anyway.

View on GitHub (pinned to 482b49bf1a)

Solutions

Remove ignore_collision from the port
Switch the network mode to host if collision ignoring is required

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at nomad/structs/structs.go:7375 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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