hashicorp/nomad · error

unsupported capacity_range for volume %q: %v

Error message

unsupported capacity_range for volume %q: %v

What it means

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".

Source

Thrown at plugins/csi/client.go:455

		switch code {
		case codes.InvalidArgument:
			return nil, fmt.Errorf(
				"volume %q snapshot source %q is not compatible with these parameters: %v",
				req.Name, req.ContentSource, err)
		case codes.NotFound:
			return nil, fmt.Errorf(
				"volume %q content source %q does not exist: %v",
				req.Name, req.ContentSource, err)
		case codes.AlreadyExists:
			return nil, fmt.Errorf(
				"volume %q already exists but is incompatible with these parameters: %v",
				req.Name, err)
		case codes.ResourceExhausted:
			return nil, fmt.Errorf(
				"unable to provision %q in accessible_topology: %v",
				req.Name, err)
		case codes.OutOfRange:
			return nil, fmt.Errorf(
				"unsupported capacity_range for volume %q: %v", req.Name, err)
		case codes.Internal:
			return nil, fmt.Errorf(
				"controller plugin returned an internal error, check the plugin allocation logs for more information: %v", err)
		}
		return nil, err
	}

	return NewCreateVolumeResponse(resp), nil
}

func (c *client) ControllerListVolumes(ctx context.Context, req *ControllerListVolumesRequest, opts ...grpc.CallOption) (*ControllerListVolumesResponse, error) {
	if err := c.ensureConnected(ctx); err != nil {
		return nil, err
	}

	err := req.Validate()
	if err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Consult the CSI plugin docs for its min/max/step volume size and set capacity_min/capacity_max within those bounds.
2. Increase the requested size to at least the plugin minimum (commonly 1GiB).
3. Round the requested size to the backend's allocation granularity (e.g. multiples of 1GiB).
4. Lower the size if it exceeds the backend's maximum volume size, or provision multiple volumes.

Example fix

// before (below plugin minimum)
capacity_min = 100000000
capacity_max = 200000000
// after
capacity_min = 1073741824
capacity_max = 2147483648

const minBytes = 1 << 30 // check against plugin docs
if req.CapacityRange.GetRequiredBytes() < minBytes {
    return fmt.Errorf("required capacity %d below plugin minimum %d", req.CapacityRange.GetRequiredBytes(), minBytes)
}
if req.CapacityRange.GetRequiredBytes()%minBytes != 0 {
    return fmt.Errorf("capacity must be a multiple of %d bytes", minBytes)
}

func validCapacity(r *csi.CapacityRange, min, max int64) bool {
    return r != nil && r.GetRequiredBytes() >= min && r.GetLimitBytes() <= max
}

vol, err := client.ControllerCreateVolume(ctx, req)
if err != nil && strings.Contains(err.Error(), "unsupported capacity_range") {
    // clamp/round the requested size per plugin limits and retry once
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• LimitBytes cannot be less than RequiredBytes
• CSI.ControllerListVolumes: plugin returned an invalid entry
• node %q has reached the maximum allowable number of attached
• volume %q is already published on another node and does not
• controller plugin returned an internal error, check the plug

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/4128e01ce392884a. Report an issue: GitHub.