hashicorp/nomad · error

failed to dispense driver %s: %v

Error message

failed to dispense driver %s: %v

What it means

In newNetworkManager, Nomad dispenses the plugin driver for each task group driver via driverManager.Dispense(task.Driver). If the driver plugin cannot be loaded/started (RPC to the driver plugin fails, plugin binary missing, plugin crashed), this error wraps the underlying cause so the allocation's network setup fails immediately.

Source

Thrown at client/allocrunner/network_manager_linux.go:68

		// the task's netmode defaults to the task group but can be overridden
		taskNetMode := tgNetMode
		if len(task.Resources.Networks) > 0 && task.Resources.Networks[0].Mode != "" {
			taskNetMode = task.Resources.Networks[0].Mode
		}

		// netmode host should always work to support backwards compat
		if taskNetMode == "host" {
			continue
		}

		// check to see if capabilities of this task's driver have already been checked
		if _, ok := driverCaps[task.Driver]; ok {
			continue
		}

		driver, err := driverManager.Dispense(task.Driver)
		if err != nil {
			return nil, fmt.Errorf("failed to dispense driver %s: %v", task.Driver, err)
		}

		caps, err := driver.Capabilities()
		if err != nil {
			return nil, fmt.Errorf("failed to retrieve capabilities for driver %s: %v",
				task.Driver, err)
		}

		// check that the driver supports the requested network isolation mode
		netIsolationMode := netModeToIsolationMode(taskNetMode)
		if !caps.HasNetIsolationMode(netIsolationMode) {
			return nil, fmt.Errorf("task %s does not support %q networking mode", task.Name, taskNetMode)
		}

		// check if the driver needs to create the network and if a different
		// driver has already claimed it needs to initiate the network
		if caps.MustInitiateNetwork {
			if networkInitiator != "" {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the driver name in the job's task 'driver' field (check spelling against drivers registered on the client).
2. Verify the driver plugin binary exists in the client's plugin_dir and is executable.
3. Check client logs for the driver plugin failing to register (plugin handshake/launch errors).
4. Ensure the driver is not disabled in client config (plugin stanza / driver allowlist).
5. Confirm the node has the driver marked healthy in 'nomad node status' before scheduling.

Example fix

// before
driver = "dockr"
// after
driver = "docker"

// before submitting a job with group networking
drivers, _, _ := client.Nodes().Info(nodeID) // check Node.Drivers[driverName].Detected && .Healthy

func driverDetected(n *api.Node, name string) bool {
  d, ok := n.Drivers[name]
  return ok && d.Detected && d.Healthy
}

When it happens

Trigger: driverManager.Dispense(task.Driver) returns an error while iterating task group drivers that have not yet been capability-checked: driver plugin not running/registered, unknown driver name in the task group, or the plugin process fails to launch.

Common situations: Typo'd driver name in the job spec (e.g. 'dockr'); external driver plugin binary missing from plugin_dir or failing to start on the node; plugin crashed after registration; driver disabled in client config.

Related errors

• DriverStatsNotImplemented
• Missing task driver
• plugin is shut down
• task not found
• failed to retrieve capabilities for driver %s: %v

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