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 a plugin instance, Nomad's driver manager asserts that the loaded plugin implements drivers.DriverPlugin. If the type assertion fails, the plugin is killed and this error is returned — the registered plugin is not a valid task driver plugin.

Source

Thrown at client/pluginmanager/drivermanager/instance.go:227

	}

	if err != nil {
		// Retry as the error just indicates the singleton has exited
		if err == singleton.SingletonPluginExited {
			pluginInstance, err = dispenseFn()
		}

		// 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 driver plugin
	driver, ok := pluginInstance.Plugin().(drivers.DriverPlugin)
	if !ok {
		pluginInstance.Kill()
		return nil, fmt.Errorf("plugin loaded does not implement the driver interface")
	}

	// Initialize the plugin if it supports it.
	if initer, ok := driver.(drivers.DriverIniter); ok {
		if err := initer.Init(i.ctx); err != nil {
			pluginInstance.Kill()
			return nil, fmt.Errorf("init of plugin %s failed: %w", i.id, err)
		}
	}

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

	// Store the reattach config
	if c, ok := pluginInstance.ReattachConfig(); ok {
		if err := i.storeReattach(c); err != nil {
			i.logger.Error("error storing driver plugin reattach config", "error", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the plugin name maps to a real task driver plugin and not another plugin type
2. Rebuild/replace the plugin binary with a version compatible with the running Nomad client's drivers.DriverPlugin interface
3. Check external plugin registration in client config (plugin "name" {...}) points to the correct executable
4. Restart the Nomad client after fixing the plugin so a fresh instance is dispensed

Example fix

// before (client config)
plugin "my-device-plugin" {}  # wrong type registered, dispensed via driver manager
// after
plugin "my-driver-plugin" {  # actual drivers.PluginBase/driver implementation
  config { ... }
}

// before dispensing, confirm the plugin is registered as a driver
mgr := client.PluginCatalog()
if _, ok := mgr[driverName]; !ok {
    return fmt.Errorf("driver %s not registered", driverName)
}

func isDriverPlugin(p plugin.Plugin) (drivers.DriverPlugin, bool) {
    d, ok := p.(drivers.DriverPlugin)
    return d, ok
}

drv, err := instance.Dispense()
if err != nil {
    if err.Error() == "plugin loaded does not implement the driver interface" {
        return fmt.Errorf("wrong plugin type registered for %s: %w", driverName, err)
    }
    return err
}

When it happens

Trigger: pluginInstance.Plugin().(drivers.DriverPlugin) fails in instance.dispense — the plugin catalog served a plugin of a different type (e.g. a device or CSI plugin registered under a driver name) or a stale/mismatched plugin build.

Common situations: Mixing Nomad/driver plugin versions after upgrade (plugin API incompatibility); registering a shared plugin (e.g. from plugin catalog config) with the wrong type; custom driver plugin not embedding the drivers interface correctly.

Related errors

• plugin is shut down
• could not validate task driver capabilities: %v
• failed to start plugin: %v
• init of plugin %s failed: %w
• ErrDriverNotFound

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