hashicorp/nomad · error

failed to create network for alloc: %v

Error message

failed to create network for alloc: %v

What it means

The network_hook's Prerun asks the client's network manager to create the allocation network (netns) via manager.CreateNetwork. Any error returned by the network manager or its underlying CNI setup is wrapped in this message and fails the allocation. The label is generic; the inner error carries the real cause.

Source

Thrown at client/allocrunner/network_hook.go:146

	// supplied hostname avoids the validation on job registrations because it
	// looks like it includes interpolation, when it doesn't.
	if interpolatedNetworks[0].Hostname != "" {
		if _, ok := dns.IsDomainName(interpolatedNetworks[0].Hostname); !ok {
			return fmt.Errorf("network hostname %q is not a valid DNS name", interpolatedNetworks[0].Hostname)
		}
	}

	// Our network create request.
	networkCreateReq := drivers.NetworkCreateRequest{
		Hostname: interpolatedNetworks[0].Hostname,
	}

	var checkedOnce bool

CREATE:
	spec, created, err := h.manager.CreateNetwork(h.alloc.ID, &networkCreateReq)
	if err != nil {
		return fmt.Errorf("failed to create network for alloc: %v", err)
	}

	if spec != nil {
		h.spec = spec
		h.isolationSetter.SetNetworkIsolation(spec)
	}

	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 {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the inner error (%v) to identify whether it's a CNI plugin, bridge, or IPAM failure.
2. Ensure CNI plugins are installed and cni_path is set correctly on the client (e.g. /opt/cni/bin with bridge plugin present).
3. Verify the client runs with sufficient privileges (root / CAP_NET_ADMIN) and that the bridge kernel module is loaded.
4. Check CNI subnet/IPAM configuration for conflicts or IP exhaustion (cni_config block in client config).
5. Restart the nomad agent after installing/changing CNI plugins so it reloads the network manager.

// pre-flight on the client: CNI plugins present
if _, err := os.Stat(filepath.Join(cniPath, "bridge")); err != nil {
    return fmt.Errorf("bridge CNI plugin missing under %s", cniPath)
}

func cniReady(cniPath string) bool {
    for _, p := range []string{"bridge", "loopback"} {
        if _, err := os.Stat(filepath.Join(cniPath, p)); err != nil { return false }
    }
    return true
}

if err := hook.Prerun(); err != nil && strings.Contains(err.Error(), "failed to create network") {
    var inner = err // inspect CNI stderr in client logs
    log.Printf("network create failed: %v; verify cni_path/plugins and privileges", inner)
}

When it happens

Trigger: h.manager.CreateNetwork(h.alloc.ID, &networkCreateReq) returns a non-nil error during Prerun — bridge/CNI plugin invocation fails, bridge driver absent, or isolation mode setup fails.

Common situations: CNI plugins not installed or CNI_PATH misconfigured on the client; missing kernel bridge module or no root privileges; malformed CNI config (e.g. bad bridge plugin conf); IP address exhaustion in the CNI subnet; nomad client not restarted after CNI install.

Related errors

• network namespace already exists but was misconfigured
• no CNI network config found
• failed to configure network manager: %v
• failed to initialize network configurator: %v
• %w: destroying network to retry failed: %v

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