{"record":{"id":"29567c4c2f486603","repo":"hashicorp/nomad","slug":"unimplemented-for-this-plugin","errorCode":null,"errorMessage":"unimplemented for this plugin","messagePattern":"unimplemented for this plugin","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/csi_endpoint.go","lineNumber":1557,"sourceCode":"\t// NOTE: this is the plugin's namespace, not the volume(s) because they\n\t// might not even be registered\n\tif !allowVolume(aclObj, args.RequestNamespace()) {\n\t\treturn structs.ErrPermissionDenied\n\t}\n\tsnap, err := v.srv.fsm.State().Snapshot()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tplugin, err := snap.CSIPluginByID(nil, args.PluginID)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif plugin == nil {\n\t\treturn fmt.Errorf(\"no such plugin\")\n\t}\n\tif !plugin.HasControllerCapability(structs.CSIControllerSupportsListVolumes) {\n\t\treturn fmt.Errorf(\"unimplemented for this plugin\")\n\t}\n\n\tmethod := \"ClientCSI.ControllerListVolumes\"\n\tcReq := &cstructs.ClientCSIControllerListVolumesRequest{\n\t\tMaxEntries:    args.PerPage,\n\t\tStartingToken: args.NextToken,\n\t}\n\tcReq.PluginID = plugin.ID\n\tcResp := &cstructs.ClientCSIControllerListVolumesResponse{}\n\n\terr = v.srv.RPC(method, cReq, cResp)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif args.PerPage > 0 && args.PerPage < int32(len(cResp.Entries)) {\n\t\t// this should be done in the plugin already, but enforce it\n\t\treply.Volumes = cResp.Entries[:args.PerPage]\n\t} else {","sourceCodeStart":1539,"sourceCodeEnd":1575,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/csi_endpoint.go#L1539-L1575","documentation":"ListExternal returns this when the plugin exists but lacks the controller capability CSIControllerSupportsListVolumes. The error is thrown before any client RPC is attempted: the plugin's reported controller capability set does not include ListVolumes, so listing external volumes via this plugin is unsupported. It is a capability negotiation failure, not a transient error.","triggerScenarios":"Calling ListExternal against a CSI plugin whose ControllerInfo (as advertised during plugin registration) omits ListVolumes support — e.g. a plugin that only supports create/delete/snapshot, or an older plugin version whose registration lacked the ListVolumes capability flag.","commonSituations":"Using a CSI plugin build/driver that doesn't implement ControllerListVolumes (many storage drivers don't); upgrading the storage driver downgraded capabilities; targeting a plugin that only runs in node-only mode without controller capabilities; invoking `nomad volume list -external` against a volume-only plugin.","solutions":["Verify the plugin supports ListVolumes: inspect the controller job's csi_plugin ControllerCapabilities / the registered plugin's ControllerInfo and use a plugin that advertises ListVolumes","Upgrade the storage driver/plugin to a version that implements the CSI ControllerListVolumes RPC with LIST_VOLUMES controller capability","If the underlying driver genuinely cannot list volumes, manage the volume listing through the vendor's own tooling instead of Nomad's ListExternal endpoint","Re-run the controller plugin registration after upgrading so the capability set is refreshed"],"exampleFix":"// before (plugin without ListVolumes capability)\ntemplate { csi_plugin { id = \"volume-only-plugin\" } } // nomad volume list -external -plugin volume-only-plugin\n// after\nplugin id = \"aws-ebs-controller\" with CONTROLLER_SERVICES = volume, capability ListVolumes; then: nomad volume list -external -plugin aws-ebs-controller","handlingStrategy":"validation","validationCode":"p, _, err := client.Plugins().Get(ctx, pluginID, nil)\nif err != nil || p == nil { return err }\nif p.ControllerInfo == nil || !p.ControllerInfo.ListVolumes {\n    return fmt.Errorf(\"plugin %q does not support ListVolumes\", pluginID)\n}","typeGuard":"func supportsListVolumes(p *api.CSIPlugin) bool {\n    return p != nil && p.ControllerInfo != nil && p.ControllerInfo.ListVolumes\n}","tryCatchPattern":"if err := listExternal(pluginID); err != nil {\n    if strings.Contains(err.Error(), \"unimplemented for this plugin\") {\n        return fmt.Errorf(\"falling back to vendor CLI for volume listing: %w\", err)\n    }\n    return err\n}","preventionTips":["Check the driver's CSI spec capabilities before wiring Nomad external volume listing to it","Pin plugin/driver versions that advertise ListVolumes controller capability","Prefer plugins whose ControllerInfo explicitly lists the capabilities you need"],"tags":["nomad","csi","capability","unsupported-operation"],"backgroundTag":"csi-capability-unsupported","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"}