{"record":{"id":"68bacdb85402bfb0","repo":"hashicorp/nomad","slug":"csi-controllervalidatevolume-v","errorCode":null,"errorMessage":"CSI.ControllerValidateVolume: %v","messagePattern":"CSI\\.ControllerValidateVolume: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/csi_endpoint.go","lineNumber":64,"sourceCode":"\t\treturn errors.New(\"CSI.ControllerValidateVolume: VolumeID is required\")\n\t}\n\n\tif req.PluginID == \"\" {\n\t\treturn errors.New(\"CSI.ControllerValidateVolume: PluginID is required\")\n\t}\n\n\tplugin, err := c.findControllerPlugin(req.PluginID)\n\tif err != nil {\n\t\t// the server's view of the plugin health is stale, so let it know it\n\t\t// should retry with another controller instance\n\t\treturn fmt.Errorf(\"CSI.ControllerValidateVolume: %w: %v\",\n\t\t\tnstructs.ErrCSIClientRPCRetryable, err)\n\t}\n\tdefer plugin.Close()\n\n\tcsiReq, err := req.ToCSIRequest()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"CSI.ControllerValidateVolume: %v\", err)\n\t}\n\n\tctx, cancelFn := c.requestContext()\n\tdefer cancelFn()\n\n\t// CSI ValidateVolumeCapabilities errors for timeout, codes.Unavailable and\n\t// codes.ResourceExhausted are retried; all other errors are fatal.\n\terr = plugin.ControllerValidateCapabilities(ctx, csiReq,\n\t\tgrpc_retry.WithPerRetryTimeout(CSIPluginRequestTimeout),\n\t\tgrpc_retry.WithMax(3),\n\t\tgrpc_retry.WithBackoff(grpc_retry.BackoffExponential(100*time.Millisecond)))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"CSI.ControllerValidateVolume: %v\", err)\n\t}\n\treturn nil\n}\n\n// ControllerAttachVolume is used to attach a volume from a CSI Cluster to","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/csi_endpoint.go#L46-L82","documentation":"ControllerValidateVolume fails when req.ToCSIRequest() cannot convert the Nomad-side request into a CSI protocol request (validating required fields such as volume ID, plugin ID, capabilities). The error is prefixed with the method name and returned unwrapped (not retryable).","triggerScenarios":"Calling ControllerValidateVolume with a request struct missing required fields, so ToCSIRequest returns a validation error before any gRPC call to the plugin.","commonSituations":"A volume registration with malformed/empty capability or volume fields; a server bug after a structs schema change (version skew between server and client); hand-crafted RPCs in tests or custom tooling.","solutions":["Inspect the underlying %v cause to find which required request field failed validation","Fix the volume registration/job volume block so required fields (volume id, plugin id, capabilities) are populated","Re-submit the volume registration or CSI RPC with a well-formed request","Check server/client Nomad versions for skew causing struct incompatibility"],"exampleFix":"// before\nreq := &structs.ClientCSIControllerValidateVolumeRequest{PluginID: \"aws-efs\"} // VolumeID empty\n// after\nreq := &structs.ClientCSIControllerValidateVolumeRequest{PluginID: \"aws-efs\", VolumeID: volID, VolumeContext: ctx, Caps: caps}","handlingStrategy":"validation","validationCode":"func validateControllerValidateReq(req *structs.ClientCSIControllerValidateVolumeRequest) error {\n    if req.PluginID == \"\" { return errors.New(\"PluginID required\") }\n    if req.VolumeID == \"\" { return errors.New(\"VolumeID required\") }\n    if len(req.Caps) == 0 { return errors.New(\"capabilities required\") }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := validateControllerValidateReq(req); err != nil {\n    // fix request fields before the RPC; this error is fatal, not retryable\n    return fmt.Errorf(\"invalid request: %w\", err)\n}","preventionTips":["Validate volume registrations with `nomad volume inspect` before validating capabilities","Keep server and client Nomad versions in lockstep","Populate Caps and VolumeContext from the volume registration, not ad-hoc","Test CSI RPC payloads in CI with representative volume specs"],"tags":["csi","validation","request-conversion"],"backgroundTag":"csi-request-validation-failed","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"}