{"record":{"id":"c0b3c6a553f780db","repo":"hashicorp/nomad","slug":"volume-q-could-not-be-found-v","errorCode":null,"errorMessage":"volume %q could not be found: %v","messagePattern":"volume %q could not be found: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"plugins/csi/client.go","lineNumber":389,"sourceCode":"func (c *client) ControllerValidateCapabilities(ctx context.Context, req *ControllerValidateVolumeRequest, opts ...grpc.CallOption) error {\n\tif err := c.ensureConnected(ctx); err != nil {\n\t\treturn err\n\t}\n\tif req.ExternalID == \"\" {\n\t\treturn fmt.Errorf(\"missing volume ID\")\n\t}\n\n\tif req.Capabilities == nil {\n\t\treturn fmt.Errorf(\"missing Capabilities\")\n\t}\n\n\tcreq := req.ToCSIRepresentation()\n\tresp, err := c.controllerClient.ValidateVolumeCapabilities(ctx, creq, opts...)\n\tif err != nil {\n\t\tcode := status.Code(err)\n\t\tswitch code {\n\t\tcase codes.NotFound:\n\t\t\terr = fmt.Errorf(\"volume %q could not be found: %v\", req.ExternalID, err)\n\t\tcase codes.Internal:\n\t\t\terr = fmt.Errorf(\"controller plugin returned an internal error, check the plugin allocation logs for more information: %v\", err)\n\t\t}\n\t\treturn err\n\t}\n\n\tif resp.Message != \"\" {\n\t\t// this should only ever be set if Confirmed isn't set, but\n\t\t// it's not a validation failure.\n\t\tc.logger.Debug(resp.Message)\n\t}\n\n\t// The protobuf accessors below safely handle nil pointers.\n\t// The CSI spec says we can only assert the plugin has\n\t// confirmed the volume capabilities, not that it hasn't\n\t// confirmed them, so if the field is nil we have to assume\n\t// the volume is ok.\n\tconfirmedCaps := resp.GetConfirmed().GetVolumeCapabilities()","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/plugins/csi/client.go#L371-L407","documentation":"The CSI controller plugin responded to ValidateVolumeCapabilities with gRPC code NotFound, meaning the volume identified by ExternalID does not exist on the storage backend. The client rewrites the gRPC status into this descriptive error including the volume ID and the original gRPC error text, since the plugin is the authority on whether a volume exists.","triggerScenarios":"Calling ControllerValidateCapabilities with an ExternalID that the storage provider does not recognize: the volume was deleted out-of-band, the ID was mistyped, the plugin is pointed at the wrong cluster/region, or the volume was never created/registered with that ID.","commonSituations":"A volume was deleted in the cloud console while Nomad still references its ID; volume registration points at a stale ID after switching storage backends; plugin misconfiguration (wrong secret/endpoint) makes it look up volumes in the wrong account; snapshot-restored or migrated environments where IDs changed.","solutions":["Verify the volume still exists in the storage backend and correct the external volume ID in the volume spec / re-register the volume with nomad volume register using the correct ID.","Check the CSI plugin's configuration (endpoint, secrets, region/cluster) to confirm it queries the storage account where the volume actually lives.","If the volume was deleted intentionally, deregister the Nomad volume (nomad volume deregister) and clean up claims referencing it.","Re-create the volume via ControllerCreateVolume if it should exist but was lost."],"exampleFix":"// before\nvolume external_id = \"vol-0abc123\"  // deleted in cloud console\n// nomad: volume could not be found\n\n// after\n$ nomad volume status vol-0abc123   # confirm failure\n# re-register with the live provider volume ID\n$ nomad volume register -volume-id=vol-0abc123 <updated-spec.hcl>","handlingStrategy":"try-catch","validationCode":"ids, err := csi.ListVolumes(ctx)\nif err != nil { return err }\nvalid := false\nfor _, v := range ids {\n    if v.Id == volID { valid = true; break }\n}\nif !valid { return fmt.Errorf(\"volume %q not present on backend\", volID) }","typeGuard":null,"tryCatchPattern":"err := client.ControllerValidateCapabilities(ctx, req)\nif err != nil {\n    if strings.Contains(err.Error(), \"could not be found\") {\n        // stop retrying; fix or re-register the volume ID\n        return fmt.Errorf(\"permanent: %w\", err)\n    }\n    return err\n}","preventionTips":["Use lifecycle automation so deleting a provider volume also deregisters it from Nomad.","Re-verify volume IDs after migrating storage backends or restoring snapshots.","Check nomad volume status output for stale registrations on a schedule."],"tags":["csi","grpc","not-found","storage"],"backgroundTag":"resource-not-found","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"}