hashicorp/nomad · error

plugin loaded does not implement the driver interface

Error message

plugin loaded does not implement the driver interface

What it means

After dispensing the plugin, the instance type-asserts the plugin to device.DevicePlugin. If the loaded plugin does not implement the device plugin interface, this error is returned and the plugin instance is killed. It is an interface-contract mismatch between the binary the loader launched and the expected go-plugin device API.

Source

Thrown at client/devicemanager/instance.go:298

	// Get an instance of the plugin
	pluginInstance, err := i.loader.Dispense(i.id.Name, i.id.PluginType, i.pluginConfig, i.logger)
	if err != nil {
		// Retry as the error just indicates the singleton has exited
		if err == singleton.SingletonPluginExited {
			pluginInstance, err = i.loader.Dispense(i.id.Name, i.id.PluginType, i.pluginConfig, i.logger)
		}

		// If we still have an error there is a real problem
		if err != nil {
			return nil, fmt.Errorf("failed to start plugin: %v", err)
		}
	}

	// Convert to a fingerprint plugin
	device, ok := pluginInstance.Plugin().(device.DevicePlugin)
	if !ok {
		pluginInstance.Kill()
		return nil, fmt.Errorf("plugin loaded does not implement the driver interface")
	}

	// Store the plugin and device
	i.plugin = pluginInstance
	i.device = device

	// Store the reattach config
	if c, ok := pluginInstance.ReattachConfig(); ok {
		i.storeReattach(c)
	}

	return device, nil
}

// cleanup shutsdown the plugin
func (i *instanceManager) cleanup() {
	i.shutdownLock.Lock()
	i.pluginLock.Lock()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the plugin binary is built as a device.DevicePlugin (correct plugin type handshake) and is compatible with this Nomad version.
2. Fix the device plugin stanza so the correct binary/type is loaded.
3. Rebuild the plugin against the same hashicorp/go-plugin and device plugin API versions used by the client.
4. Restart the nomad client after correcting the plugin.

Example fix

// before: serving a driver plugin under device manager
func main() { plugin.Serve(&plugin.ServeConfig{HandshakeConfig: driverHandshake, ...}) }
// after: serve the device plugin set
func main() { plugin.Serve(&plugin.ServeConfig{HandshakeConfig: deviceHandshake, Plugins: map[string]plugin.Plugin{"device": &device.DevicePlugin{Impl: d}}} ) }

// verify the plugin serves the device type before wiring it up
// `nomad plugin status <id>` should list it under Device Plugins

func asDevicePlugin(p plugin.Plugin) (device.DevicePlugin, bool) {
  d, ok := p.(device.DevicePlugin)
  return d, ok
}

dev, err := instance.dispense()
if err != nil && strings.Contains(err.Error(), "driver interface") {
  // wrong binary or API version: replace plugin binary
  log.Errorf("plugin %s is not a DevicePlugin: %v", name, err)
}

When it happens

Trigger: A plugin binary registered as a device plugin actually exposes a different plugin type (e.g. a task driver or CSI plugin served over the same go-plugin machinery) or was built against an incompatible plugin API version.

Common situations: Wrong binary configured under device plugins; plugin built for a different Nomad/go-plugin protocol version; misnamed plugin served a driver instead of a device plugin.

Related errors

• CSI Plugin loaded incorrectly
• failed to start plugin: %v
• failed to reattach to plugin %q: %v
• plugin loaded does not implement the driver interface
• plugin not found

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