{"record":{"id":"063ac7136f38f477","repo":"hashicorp/nomad","slug":"plugin-loaded-does-not-implement-the-driver-interf","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/devicemanager/instance.go","lineNumber":298,"sourceCode":"\t// Get an instance of the plugin\n\tpluginInstance, err := i.loader.Dispense(i.id.Name, i.id.PluginType, i.pluginConfig, i.logger)\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 = i.loader.Dispense(i.id.Name, i.id.PluginType, i.pluginConfig, i.logger)\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 fingerprint plugin\n\tdevice, ok := pluginInstance.Plugin().(device.DevicePlugin)\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// Store the plugin and device\n\ti.plugin = pluginInstance\n\ti.device = device\n\n\t// Store the reattach config\n\tif c, ok := pluginInstance.ReattachConfig(); ok {\n\t\ti.storeReattach(c)\n\t}\n\n\treturn device, nil\n}\n\n// cleanup shutsdown the plugin\nfunc (i *instanceManager) cleanup() {\n\ti.shutdownLock.Lock()\n\ti.pluginLock.Lock()","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/devicemanager/instance.go#L280-L316","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the plugin binary is built as a device.DevicePlugin (correct plugin type handshake) and is compatible with this Nomad version.","Fix the device plugin stanza so the correct binary/type is loaded.","Rebuild the plugin against the same hashicorp/go-plugin and device plugin API versions used by the client.","Restart the nomad client after correcting the plugin."],"exampleFix":"// before: serving a driver plugin under device manager\nfunc main() { plugin.Serve(&plugin.ServeConfig{HandshakeConfig: driverHandshake, ...}) }\n// after: serve the device plugin set\nfunc main() { plugin.Serve(&plugin.ServeConfig{HandshakeConfig: deviceHandshake, Plugins: map[string]plugin.Plugin{\"device\": &device.DevicePlugin{Impl: d}}} ) }","handlingStrategy":"type-guard","validationCode":"// verify the plugin serves the device type before wiring it up\n// `nomad plugin status <id>` should list it under Device Plugins","typeGuard":"func asDevicePlugin(p plugin.Plugin) (device.DevicePlugin, bool) {\n  d, ok := p.(device.DevicePlugin)\n  return d, ok\n}","tryCatchPattern":"dev, err := instance.dispense()\nif err != nil && strings.Contains(err.Error(), \"driver interface\") {\n  // wrong binary or API version: replace plugin binary\n  log.Errorf(\"plugin %s is not a DevicePlugin: %v\", name, err)\n}","preventionTips":["Serve the device.DevicePlugin plugin set in the plugin binary's main","Rebuild plugins against the Nomad/go-plugin API version in use","Test plugin handshake (`nomad plugin status`) after every plugin upgrade"],"tags":["plugin","devicemanager","type-assertion"],"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"}