hashicorp/nomad · error

failed to configure networking for alloc: %v

Error message

failed to configure networking for alloc: %v

What it means

The network_hook's Prerun returns this when manager.ConfigureNetwork fails after the one-shot destroy-and-retry (i.e. the retry either wasn't triggered by ErrCNICheckFailed or also failed). The inner error from CNI configuration carries the actual cause; this wrapper just marks networking configuration as the failing stage.

Source

Thrown at client/allocrunner/network_hook.go:170

	}

	if spec != nil {
		status, err := h.networkConfigurator.Setup(context.TODO(), h.alloc, spec, created)
		if err != nil {
			// if the netns already existed but is invalid, we get
			// ErrCNICheckFailed. We'll try to recover from this one time by
			// recreating the netns from scratch before giving up
			if errors.Is(err, ErrCNICheckFailed) && !checkedOnce {
				h.logger.Warn("network configuration check failed", "error", err)
				checkedOnce = true
				destroyErr := h.manager.DestroyNetwork(h.alloc.ID, spec)
				if destroyErr != nil {
					return fmt.Errorf("%w: destroying network to retry failed: %v", err, destroyErr)
				}
				goto CREATE
			}

			return fmt.Errorf("failed to configure networking for alloc: %v", err)
		}
		// A nil status indicates a netns already exists and is configured correctly.
		// It should have been saved to the local state store.
		if status == nil {
			stateStatus := h.networkStatus.NetworkStatus()
			if stateStatus == nil {
				return errors.New("network already configured but not found in state")
			}
			status = stateStatus
		}

		// If the driver set the sandbox hostname label, then we will use that
		// to set the HostsConfig.Hostname. Otherwise, identify the sandbox
		// container ID which will have been used to set the network namespace
		// hostname.
		if hostname, ok := spec.Labels[dockerNetSpecHostnameKey]; ok {
			h.spec.HostsConfig = &drivers.HostsConfig{
				Address:  status.Address,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped inner error and the nomad client logs for the CNI stderr output.
2. Validate the CNI network configuration files (JSON validity, plugin names, subnet conflicts).
3. Fix resource conflicts: free ports used by port mappings, expand the IPAM subnet, or remove conflicting bridges.
4. Recreate the alloc to get a fresh netns (nomad alloc stop, reschedule).
5. Restart the client / reconcile network state if stale namespaces persist.

// pre-flight: verify CNI conf validity and free port ranges
var conf map[string]interface{}
if err := json.Unmarshal(cniConf, &conf); err != nil {
    return fmt.Errorf("invalid CNI config: %w", err)
}

func configureFailed(err error) bool {
    return err != nil && strings.Contains(err.Error(), "failed to configure networking")
}

if err := hook.Prerun(); err != nil && strings.Contains(err.Error(), "failed to configure networking") {
    log.Printf("CNI configure failed: %v — check CNI stderr in client logs", err)
    // fix config/ports/IPs then reschedule the alloc
}

When it happens

Trigger: Prerun: ConfigureNetwork(h.alloc.ID, spec, ...) returns a non-nil error and either it is not ErrCNICheckFailed or the single retry (goto CREATE) already happened and failed again.

Common situations: CNI ADD failures: port mapping conflicts, bandwidth plugin errors, malformed CNI chaining config, IP allocation failures, tc/netem misconfig, or persistent bridge conflicts that survive the recreate retry.

Related errors

• no CNI network config found
• failed to initialize network configurator: %v
• network namespace already exists but was misconfigured
• failed to configure network manager: %v
• failed to create network for alloc: %v

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