{"record":{"id":"afb8a1a9a0acd902","repo":"hashicorp/nomad","slug":"csi-plugin-failed-to-register-w","errorCode":null,"errorMessage":"CSI plugin failed to register: %w","messagePattern":"CSI plugin failed to register: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/taskrunner/plugin_supervisor_hook.go","lineNumber":330,"sourceCode":"\t\t\t\tt.Reset(5 * time.Second)\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\t// Mark the plugin as healthy in a task event\n\t\t\th.logger.Debug(\"CSI plugin is ready\")\n\t\t\th.previousHealthState = pluginHealthy\n\t\t\tevent := structs.NewTaskEvent(structs.TaskPluginHealthy)\n\t\t\tevent.SetMessage(fmt.Sprintf(\"plugin: %s\", h.task.CSIPluginConfig.ID))\n\t\t\th.eventEmitter.EmitEvent(event)\n\n\t\t\tbreak WAITFORREADY\n\t\t}\n\t}\n\n\t// Step 2: Register the plugin with the catalog.\n\tderegisterPluginFn, err := h.registerPlugin(client, h.socketPath)\n\tif err != nil {\n\t\th.restartTask(ctx, fmt.Errorf(\"CSI plugin failed to register: %w\", err))\n\t\treturn\n\t}\n\t// De-register plugins on task shutdown\n\tdefer deregisterPluginFn()\n\n\t// Step 3: Start the lightweight supervisor loop. At this point,\n\t// probe failures don't cause the task to restart\n\tt.Reset(0)\n\tfor {\n\t\tselect {\n\t\tcase <-supervisorCtx.Done():\n\t\t\treturn\n\t\tcase <-t.C:\n\t\t\tpluginHealthy, err := h.supervisorLoopOnce(supervisorCtx, client)\n\t\t\tif err != nil {\n\t\t\t\th.logger.Error(\"CSI plugin fingerprinting failed\", \"error\", err)\n\t\t\t}\n","sourceCodeStart":312,"sourceCodeEnd":348,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/taskrunner/plugin_supervisor_hook.go#L312-L348","documentation":"Nomad wraps any error from registerPlugin with this message when the CSI plugin could not be registered into the plugin catalog after the task started. The wrap happens in ensureSupervisorLoop, and the wrapped error triggers restartTask, so the task is restarted in an attempt to recover the plugin registration.","triggerScenarios":"The CSI plugin task starts and its socket accepts connections, but h.registerPlugin fails — typically client.PluginInfo() errors (timeout, gRPC failure, bad socket path) or the dynamic registration into the catalog fails. ensureSupervisorLoop (called via Poststart) then calls h.restartTask with this wrapped error.","commonSituations":"Plugin container starts but its CSI endpoint is slow or never ready within the probe timeout; csi_plugin.mount_config/stage/permission stanza misconfiguration causing a wrong socket path; plugin image lacking the CSI identity service; NFS/emptyDir volume where the socket never appears; Nomad client cannot reach the plugin over the Unix socket.","solutions":["Check the plugin container logs to see why the CSI endpoint failed to serve PluginInfo","Verify csi_plugin block config (id, type, mount_dir) matches where the plugin exposes its socket","Increase liveness/registration timeouts (e.g. plugin stanza's csi_agent_timeout / task resources) if the plugin is slow to start","Confirm the socket path is on a shared mount visible to the Nomad client, not an isolated filesystem","Ensure the plugin image implements the CSI Identity service (NodePluginInfo/GetPluginInfo)"],"exampleFix":"// before\nplugin \"aws-efs\" {\n  type = \"node\"\n  mount_dir = \"/csi\"\n}\n// after\nplugin \"aws-efs\" {\n  type        = \"node\"\n  id          = \"aws-efs\"\n  mount_dir   = \"/csi\"\n  healthchecks { liveness_probe { ... } } # ensure plugin endpoint is actually up\n}","handlingStrategy":"retry","validationCode":"// before starting the task, verify the CSI plugin endpoint is reachable\nfunc pluginSocketReady(socketPath string) error {\n    _, err := os.Stat(socketPath)\n    return err // must exist before registration probes succeed\n}","typeGuard":null,"tryCatchPattern":"// tolerate and retry registration: restartTask already retries\nticker := time.NewTicker(10 * time.Second)\nfor attempt := 0; attempt < 5; attempt++ {\n    dereg, err := registerPlugin(client, socketPath)\n    if err == nil { defer dereg(); break }\n    log.Warnf(\"CSI plugin registration failed, retrying: %v\", err)\n    <-ticker.C\n}","preventionTips":["Pre-validate the csi_plugin stanza (id, type, mount_dir) before deployment","Monitor plugin container health and restarts","Ensure the socket directory is on a volume shared between plugin and Nomad client","Pin plugin images to tested versions and include CSI Identity service conformance tests"],"tags":["nomad","csi","plugin-registration","grpc","restart-loop"],"backgroundTag":"csi-plugin-registration-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}