{"record":{"id":"4128e01ce392884a","repo":"hashicorp/nomad","slug":"unsupported-capacity-range-for-volume-q-v","errorCode":null,"errorMessage":"unsupported capacity_range for volume %q: %v","messagePattern":"unsupported capacity_range for volume %q: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"plugins/csi/client.go","lineNumber":455,"sourceCode":"\t\tswitch code {\n\t\tcase codes.InvalidArgument:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"volume %q snapshot source %q is not compatible with these parameters: %v\",\n\t\t\t\treq.Name, req.ContentSource, err)\n\t\tcase codes.NotFound:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"volume %q content source %q does not exist: %v\",\n\t\t\t\treq.Name, req.ContentSource, err)\n\t\tcase codes.AlreadyExists:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"volume %q already exists but is incompatible with these parameters: %v\",\n\t\t\t\treq.Name, err)\n\t\tcase codes.ResourceExhausted:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"unable to provision %q in accessible_topology: %v\",\n\t\t\t\treq.Name, 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.Name, err)\n\t\tcase codes.Internal:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"controller plugin returned an internal error, check the plugin allocation logs for more information: %v\", err)\n\t\t}\n\t\treturn nil, err\n\t}\n\n\treturn NewCreateVolumeResponse(resp), nil\n}\n\nfunc (c *client) ControllerListVolumes(ctx context.Context, req *ControllerListVolumesRequest, opts ...grpc.CallOption) (*ControllerListVolumesResponse, error) {\n\tif err := c.ensureConnected(ctx); err != nil {\n\t\treturn nil, err\n\t}\n\n\terr := req.Validate()\n\tif err != nil {","sourceCodeStart":437,"sourceCodeEnd":473,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/plugins/csi/client.go#L437-L473","documentation":"ControllerCreateVolume received gRPC code OutOfRange from the CSI plugin: the capacity_range in the CreateVolumeRequest is outside what the plugin supports (too small, too large, or not respecting a required minimum/step). Nomad translates this to \"unsupported capacity_range\".","triggerScenarios":"Calling ControllerCreateVolume where requested capacity_bytes violates the plugin's limits — below the minimum volume size, above the maximum, or not a multiple of the backend's allocation unit.","commonSituations":"Volume spec `capacity_min`/`capacity_max` set below the plugin's minimum (e.g. many backends require >=1GiB or several GiB); typo like capacity in bytes vs GiB; backend max volume size exceeded; rounding rules (multiples of 1GiB) violated.","solutions":["Consult the CSI plugin docs for its min/max/step volume size and set capacity_min/capacity_max within those bounds.","Increase the requested size to at least the plugin minimum (commonly 1GiB).","Round the requested size to the backend's allocation granularity (e.g. multiples of 1GiB).","Lower the size if it exceeds the backend's maximum volume size, or provision multiple volumes."],"exampleFix":"// before (below plugin minimum)\ncapacity_min = 100000000\ncapacity_max = 200000000\n// after\ncapacity_min = 1073741824\ncapacity_max = 2147483648","handlingStrategy":"validation","validationCode":"const minBytes = 1 << 30 // check against plugin docs\nif req.CapacityRange.GetRequiredBytes() < minBytes {\n    return fmt.Errorf(\"required capacity %d below plugin minimum %d\", req.CapacityRange.GetRequiredBytes(), minBytes)\n}\nif req.CapacityRange.GetRequiredBytes()%minBytes != 0 {\n    return fmt.Errorf(\"capacity must be a multiple of %d bytes\", minBytes)\n}","typeGuard":"func validCapacity(r *csi.CapacityRange, min, max int64) bool {\n    return r != nil && r.GetRequiredBytes() >= min && r.GetLimitBytes() <= max\n}","tryCatchPattern":"vol, err := client.ControllerCreateVolume(ctx, req)\nif err != nil && strings.Contains(err.Error(), \"unsupported capacity_range\") {\n    // clamp/round the requested size per plugin limits and retry once\n}","preventionTips":["Read the plugin's min/max/step size requirements and encode them in spec templates.","Always express sizes in GiB multiples (1073741824 bytes) in volume specs.","Add CI lint checks on capacity_min/capacity_max values."],"tags":["csi","grpc","storage","capacity-range"],"backgroundTag":"unsupported-capacity-range","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"}