{"record":{"id":"cb762ab23f4dfe60","repo":"hashicorp/nomad","slug":"requested-capabilities-not-compatible-with-volume","errorCode":null,"errorMessage":"requested capabilities not compatible with volume %q: %v","messagePattern":"requested capabilities not compatible with volume %q: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"plugins/csi/client.go","lineNumber":531,"sourceCode":"\t}\n\treturn err\n}\n\nfunc (c *client) ControllerExpandVolume(ctx context.Context, req *ControllerExpandVolumeRequest, opts ...grpc.CallOption) (*ControllerExpandVolumeResponse, error) {\n\tif err := req.Validate(); err != nil {\n\t\treturn nil, err\n\t}\n\tif err := c.ensureConnected(ctx); err != nil {\n\t\treturn nil, err\n\t}\n\n\texReq := req.ToCSIRepresentation()\n\tresp, err := c.controllerClient.ControllerExpandVolume(ctx, exReq, opts...)\n\tif err != nil {\n\t\tcode := status.Code(err)\n\t\tswitch code {\n\t\tcase codes.InvalidArgument:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"requested capabilities not compatible with volume %q: %v\",\n\t\t\t\treq.ExternalVolumeID, err)\n\t\tcase codes.NotFound:\n\t\t\terr = fmt.Errorf(\"volume %q could not be found: %v\", req.ExternalVolumeID, err)\n\t\tcase codes.FailedPrecondition:\n\t\t\terr = fmt.Errorf(\"volume %q cannot be expanded online: %v\", req.ExternalVolumeID, err)\n\t\tcase codes.OutOfRange:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"unsupported capacity_range for volume %q: %v\", req.ExternalVolumeID, 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\tdefault:\n\t\t\terr = fmt.Errorf(\"controller plugin returned an error: %v\", err)\n\t\t}\n\t\treturn nil, err\n\t}\n\n\treturn &ControllerExpandVolumeResponse{","sourceCodeStart":513,"sourceCodeEnd":549,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/plugins/csi/client.go#L513-L549","documentation":"This error is returned by the CSI client's ControllerExpandVolume when the storage plugin's controller responds with gRPC status InvalidArgument. It means the volume capabilities (access mode, access type, filesystem) in the expansion request were rejected as incompatible with the existing volume on the storage backend. The library maps the raw gRPC status code to this human-readable message so callers can distinguish capability mismatches from other expansion failures. The underlying plugin error text is appended for diagnostics.","triggerScenarios":"Calling ControllerExpandVolume (e.g. via Nomad's volume expansion path) with a ControllerExpandVolumeRequest whose VolumeCapability does not match how the volume was originally created, and the CSI plugin replies with codes.InvalidArgument.","commonSituations":"Changing the access mode (e.g. MULTI_NODE_READER_ONLY to SINGLE_NODE_WRITER) or filesystem type between volume creation and expansion; a plugin upgrade that changed capability validation; running expansion against a volume created by a different driver or with different mount options.","solutions":["Inspect the appended gRPC error detail to identify which capability field was rejected.","Ensure the ControllerExpandVolumeRequest capability matches the volume's original creation capabilities exactly (access mode, mount volume/filesystem).","Re-create the volume with the desired capabilities instead of expanding an incompatible one.","Check the CSI plugin version/docs for capability restrictions on online expansion."],"exampleFix":"// before\nreq := &csi.ControllerExpandVolumeRequest{\n    ExternalVolumeID: id,\n    CapacityRange:    &csi.CapacityRange{RequiredBytes: newSize},\n    // capability omitted or changed from creation time\n}\n// after\nreq := &csi.ControllerExpandVolumeRequest{\n    ExternalVolumeID: id,\n    CapacityRange:    &csi.CapacityRange{RequiredBytes: newSize},\n    VolumeCapability: originalCreationCapability, // same access mode + fs as at creation\n}","handlingStrategy":"try-catch","validationCode":"if req.CapacityRange == nil || req.CapacityRange.RequiredBytes <= currentVol.CapacityBytes {\n    return fmt.Errorf(\"required bytes must be greater than current size %d\", currentVol.CapacityBytes)\n}\n// ensure capability matches creation-time capability\nif !reflect.DeepEqual(req.VolumeCapability, creationSpec.VolumeCapability) {\n    return fmt.Errorf(\"expansion capability must match original volume capability\")\n}","typeGuard":"func isInvalidArgumentErr(err error) bool {\n    if err == nil { return false }\n    return strings.Contains(err.Error(), \"requested capabilities not compatible with volume\")\n}","tryCatchPattern":"resp, err := client.ControllerExpandVolume(ctx, req)\nif err != nil {\n    if strings.Contains(err.Error(), \"requested capabilities not compatible with volume\") {\n        // fix capability in the volume spec to match creation-time capability\n        return fmt.Errorf(\"fix volume capability: %w\", err)\n    }\n    return err\n}","preventionTips":["Store and reuse the exact VolumeCapability used at volume creation when expanding.","Never change access mode or filesystem type between create and expand operations.","Pin and test your CSI plugin version; capability validation rules can change between releases."],"tags":["csi","grpc","volume-expansion","invalid-argument"],"backgroundTag":"csi-capability-mismatch","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"}