hashicorp/nomad · error

failed to retrieve capabilities for driver %s: %v

Error message

failed to retrieve capabilities for driver %s: %v

What it means

After dispensing a driver, newNetworkManager calls driver.Capabilities() to learn the driver's supported network isolation modes. If that RPC to the driver plugin fails, this error wraps it. It means the driver process was reachable enough to dispense but failed to answer the Capabilities call.

Source

Thrown at client/allocrunner/network_manager_linux.go:73

		// 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 != "" {
				return nil, fmt.Errorf("tasks %s and %s want to initiate networking but only one driver can do so", networkInitiator, task.Name)
			}
			netManager, ok := driver.(drivers.DriverNetworkManager)
			if !ok {
				return nil, fmt.Errorf("driver %s does not implement network management RPCs", task.Driver)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Restart the Nomad client so the driver plugin relaunches and re-registers.
2. Check client logs around the error for the underlying plugin RPC failure/panic.
3. Upgrade or reinstall the driver plugin binary to a version matching the Nomad client.
4. Verify plugin process health on the host (ps/lsof on the plugin socket).

// ensure plugin process is alive before scheduling
systemctl is-active nomad-driver-<name> || systemctl restart nomad-driver-<name>

// on client: wrap driver RPC calls
if err := drv.Capabilities(); err != nil {
  logger.Error("driver caps rpc failed, restarting plugin", "err", err)
  // plugin supervisor restarts; retry with backoff
}

When it happens

Trigger: driver.Capabilities() returns an error during newNetworkManager's per-driver loop: driver plugin crashed/hung mid-call, RPC timeout to plugin, or plugin returning an error from its Capabilities implementation.

Common situations: Driver plugin process died after registration (OOM, panic); communication issues with the plugin over its unix socket; a buggy/old plugin version whose Capabilities implementation errors.

Related errors

• DriverStatsNotImplemented
• volume requested capabilities update was not compatible with
• Missing task driver
• plugin is shut down
• Invalid namespace capability '%s': %#v

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