hashicorp/nomad · error

failed to configure network: %v

Error message

failed to configure network: %v

What it means

CNI plugin invocation (c.cni.Setup) failed while creating the allocation's network namespace/bridge (IPAM failure, missing plugin binary, or transient race creating the nomad bridge). Setup retries up to 3 times; this wrapped error is returned after final failure, leaving the alloc without networking.

Source

Thrown at client/allocrunner/networking_cni.go:226

	// Depending on the version of bridge cni plugin used, a known race could occure
	// where two alloc attempt to create the nomad bridge at the same time, resulting
	// in one of them to fail. This rety attempts to overcome those erroneous failures.
	const retry = 3
	var firstError error
	var res *cni.Result
	for attempt := 1; ; attempt++ {
		var err error
		if res, err = c.cni.Setup(ctx, alloc.ID, spec.Path,
			c.nsOpts.withCapabilityPortMap(portMaps.ports),
			c.nsOpts.withArgs(cniArgs),
		); err != nil {
			c.logger.Warn("failed to configure network", "error", err, "attempt", attempt)
			switch attempt {
			case 1:
				firstError = err
			case retry:
				return nil, fmt.Errorf("failed to configure network: %v", firstError)
			}

			// Sleep for 1 second + jitter
			time.Sleep(time.Second + (time.Duration(c.rand.Int63n(1000)) * time.Millisecond))
			continue
		}
		break
	}

	if c.logger.IsDebug() {
		resultJSON, _ := json.Marshal(res)
		c.logger.Debug("received result from CNI", "result", string(resultJSON))
	}

	allocNet, err := c.cniToAllocNet(res)
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the wrapped CNI error and client logs for the per-attempt warnings
2. Verify CNI plugin binaries (bridge, loopback, iptables) are installed in the CNI path
3. Check IPAM subnet exhaustion and leftover bridges/iptables state
4. Clean stale iptables rules/nomad bridges and retry the allocation

When it happens

Trigger: Thrown at client/allocrunner/networking_cni.go:226 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/e555e6987971eca1. Report an issue: GitHub.