hashicorp/nomad · error

driver %s does not implement network management RPCs

Error message

driver %s does not implement network management RPCs

What it means

When a driver claims MustInitiateNetwork, it must also implement the drivers.DriverNetworkManager interface (CreateNetwork/DestroyNetwork RPCs). If the type assertion fails, Nomad cannot delegate network lifecycle RPCs to it and rejects the allocation.

Source

Thrown at client/allocrunner/network_manager_linux.go:91

			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)
			}

			nm = netManager
			networkInitiator = task.Name
		} else if len(tg.Networks) > 0 && tg.Networks[0].Hostname != "" {
			// TODO jrasell: remove once the default linux network manager
			//  supports setting the hostname in bridged mode. This currently
			//  indicates only Docker supports this, which is true unless a
			//  custom driver can which means this check still holds as true as
			//  we can tell.
			//  Please see: https://github.com/hashicorp/nomad/issues/11180
			return nil, fmt.Errorf("hostname is not currently supported on driver %s", task.Driver)
		}

		// mark this driver's capabilities as checked
		driverCaps[task.Driver] = struct{}{}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rebuild/upgrade the driver plugin against a Nomad SDK version that includes DriverNetworkManager.
2. Downgrade or align the plugin with the Nomad client version.
3. Remove MustInitiateNetwork from the custom driver's capabilities if it cannot implement network management RPCs.
4. Use a built-in driver (e.g. docker) for tasks that require group bridge networking.

Example fix

// before (custom driver)
func (d *Driver) Capabilities() (*drivers.Capabilities, error) {
  return &drivers.Capabilities{MustInitiateNetwork: true}, nil
}
// after
func (d *Driver) Capabilities() (*drivers.Capabilities, error) {
  return &drivers.Capabilities{MustInitiateNetwork: false}, nil
}

func implementsDriverNetworkManager(d drivers.DriverPlugin) bool {
  _, ok := d.(drivers.DriverNetworkManager)
  return ok
}

When it happens

Trigger: driver.(drivers.DriverNetworkManager) type assertion fails during newNetworkManager for a driver whose caps set MustInitiateNetwork=true — i.e. an old or custom driver plugin that declares network initiation but wasn't built against the DriverNetworkManager RPC interface.

Common situations: Out-of-tree/legacy driver plugin compiled against an older Nomad drivers SDK; mismatched plugin and Nomad client versions; a custom driver incorrectly advertising MustInitiateNetwork.

Related errors

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

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