{"record":{"id":"d36cb73d47cc8893","repo":"hashicorp/nomad","slug":"no-healthy-controllers-for-csi-plugin-s","errorCode":null,"errorMessage":"no healthy controllers for CSI plugin: %s","messagePattern":"no healthy controllers for CSI plugin: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/csi_endpoint.go","lineNumber":230,"sourceCode":"\t\t\treply.Volume = vol\n\t\t\treturn v.srv.replySetIndex(csiVolumeTable, &reply.QueryMeta)\n\t\t}}\n\treturn v.srv.blockingRPC(&opts)\n}\n\nfunc (v *CSIVolume) pluginValidateVolume(vol *structs.CSIVolume) (*structs.CSIPlugin, error) {\n\tstate := v.srv.fsm.State()\n\n\tplugin, err := state.CSIPluginByID(nil, vol.PluginID)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif plugin == nil {\n\t\treturn nil, fmt.Errorf(\"no CSI plugin named: %s could be found\", vol.PluginID)\n\t}\n\n\tif plugin.ControllerRequired && plugin.ControllersHealthy < 1 {\n\t\treturn nil, fmt.Errorf(\"no healthy controllers for CSI plugin: %s\", vol.PluginID)\n\t}\n\n\tvol.Provider = plugin.Provider\n\tvol.ProviderVersion = plugin.Version\n\n\treturn plugin, nil\n}\n\nfunc (v *CSIVolume) controllerValidateVolume(req *structs.CSIVolumeRegisterRequest, vol *structs.CSIVolume, plugin *structs.CSIPlugin) error {\n\n\tif !plugin.ControllerRequired {\n\t\t// The plugin does not require a controller, so for now we won't do any\n\t\t// further validation of the volume.\n\t\treturn nil\n\t}\n\n\tmethod := \"ClientCSI.ControllerValidateVolume\"\n\tcReq := &cstructs.ClientCSIControllerValidateVolumeRequest{","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/csi_endpoint.go#L212-L248","documentation":"Fires in pluginValidateVolume: the CSI plugin exists and requires a controller, but ControllersHealthy is zero — no controller instances of the plugin are currently healthy, so volume operations needing a controller cannot proceed.","triggerScenarios":"Registering or creating a volume on a plugin with ControllerRequired=true when no controller healthy count is >= 1, typically because controller instances are down or just registered.","commonSituations":"CSI controller task crashed or OOMed; controller not scheduled due to node constraints; plugin just started and health hasn't been established yet; cluster after node failure.","solutions":["Check nomad plugin status <plugin> for controller health and restart the CSI controller job","Fix scheduling constraints so the controller can be placed on an eligible node","Wait for plugin health to update after (re)starting the controller, then retry"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"p, _ := client.CSIPlugins().Get(pluginID, nil)\nif p != nil && p.ControllersHealthy < 1 {\n    return errors.New(\"controller unhealthy; abort volume registration\")\n}","typeGuard":"func controllersHealthy(p *api.CSIPlugin) bool { return p != nil && p.ControllersHealthy >= 1 }","tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"no healthy controllers\") { wait/restart controller then retry }","preventionTips":["Monitor plugin controller health before volume operations","Set correct datacenter/constraints so controllers schedule","Retry after controller (re)registration with backoff"],"tags":["csi","plugin","health"],"backgroundTag":"csi-no-healthy-controllers","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"}