{"record":{"id":"db553e09368427c9","repo":"hashicorp/nomad","slug":"plugin-loaded-does-not-implement-the-driver-interf-db553e","errorCode":null,"errorMessage":"plugin loaded does not implement the driver interface","messagePattern":"plugin loaded does not implement the driver interface","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/pluginmanager/drivermanager/instance.go","lineNumber":227,"sourceCode":"\t}\n\n\tif err != nil {\n\t\t// Retry as the error just indicates the singleton has exited\n\t\tif err == singleton.SingletonPluginExited {\n\t\t\tpluginInstance, err = dispenseFn()\n\t\t}\n\n\t\t// If we still have an error there is a real problem\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to start plugin: %v\", err)\n\t\t}\n\t}\n\n\t// Convert to a driver plugin\n\tdriver, ok := pluginInstance.Plugin().(drivers.DriverPlugin)\n\tif !ok {\n\t\tpluginInstance.Kill()\n\t\treturn nil, fmt.Errorf(\"plugin loaded does not implement the driver interface\")\n\t}\n\n\t// Initialize the plugin if it supports it.\n\tif initer, ok := driver.(drivers.DriverIniter); ok {\n\t\tif err := initer.Init(i.ctx); err != nil {\n\t\t\tpluginInstance.Kill()\n\t\t\treturn nil, fmt.Errorf(\"init of plugin %s failed: %w\", i.id, err)\n\t\t}\n\t}\n\n\t// Store the plugin and driver\n\ti.plugin = pluginInstance\n\ti.driver = driver\n\n\t// Store the reattach config\n\tif c, ok := pluginInstance.ReattachConfig(); ok {\n\t\tif err := i.storeReattach(c); err != nil {\n\t\t\ti.logger.Error(\"error storing driver plugin reattach config\", \"error\", err)","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/pluginmanager/drivermanager/instance.go#L209-L245","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the plugin name maps to a real task driver plugin and not another plugin type","Rebuild/replace the plugin binary with a version compatible with the running Nomad client's drivers.DriverPlugin interface","Check external plugin registration in client config (plugin \"name\" {...}) points to the correct executable","Restart the Nomad client after fixing the plugin so a fresh instance is dispensed"],"exampleFix":"// before (client config)\nplugin \"my-device-plugin\" {}  # wrong type registered, dispensed via driver manager\n// after\nplugin \"my-driver-plugin\" {  # actual drivers.PluginBase/driver implementation\n  config { ... }\n}","handlingStrategy":"validation","validationCode":"// before dispensing, confirm the plugin is registered as a driver\nmgr := client.PluginCatalog()\nif _, ok := mgr[driverName]; !ok {\n    return fmt.Errorf(\"driver %s not registered\", driverName)\n}","typeGuard":"func isDriverPlugin(p plugin.Plugin) (drivers.DriverPlugin, bool) {\n    d, ok := p.(drivers.DriverPlugin)\n    return d, ok\n}","tryCatchPattern":"drv, err := instance.Dispense()\nif err != nil {\n    if err.Error() == \"plugin loaded does not implement the driver interface\" {\n        return fmt.Errorf(\"wrong plugin type registered for %s: %w\", driverName, err)\n    }\n    return err\n}","preventionTips":["Register only task driver plugins under driver manager plugin names","Keep external plugin builds in lockstep with Nomad's drivers interface version","Verify plugin registration type in client config before startup","Test plugin launches after every Nomad upgrade"],"tags":["nomad","plugin","driver","type-assertion","compatibility"],"backgroundTag":"plugin-interface-mismatch","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}