hashicorp/nomad · error
LimitBytes cannot be less than RequiredBytes
Error message
LimitBytes cannot be less than RequiredBytes
What it means
This error is returned by VolumeOptions.Validate in the CSI plugin client when a volume request's CapacityRange sets a positive LimitBytes that is smaller than RequiredBytes. The CSI spec requires that the limit (maximum capacity the CO can accept) be greater than or equal to the required capacity (minimum the SP must provide), so a contradictory range is rejected before any gRPC call is made. It is a fail-fast guard to avoid a guaranteed rejection by the storage provider.
Source
Thrown at plugins/csi/plugin.go:506
return req
}
func (r *ControllerCreateVolumeRequest) Validate() error {
if r.Name == "" {
return errors.New("missing Name")
}
if r.VolumeCapabilities == nil {
return errors.New("missing VolumeCapabilities")
}
if r.CapacityRange != nil {
if r.CapacityRange.LimitBytes == 0 && r.CapacityRange.RequiredBytes == 0 {
return errors.New(
"one of LimitBytes or RequiredBytes must be set if CapacityRange is set")
}
if r.CapacityRange.LimitBytes > 0 &&
r.CapacityRange.LimitBytes < r.CapacityRange.RequiredBytes {
return errors.New("LimitBytes cannot be less than RequiredBytes")
}
}
if r.ContentSource != nil {
if r.ContentSource.CloneID != "" && r.ContentSource.SnapshotID != "" {
return errors.New(
"one of SnapshotID or CloneID must be set if ContentSource is set")
}
}
return nil
}
// VolumeContentSource is snapshot or volume that the plugin will use to
// create the new volume. At most one of these fields can be set, but nil (and
// not an empty struct) is expected by CSI plugins if neither field is set.
type VolumeContentSource struct {
SnapshotID string
CloneID string
}View on GitHub (pinned to 482b49bf1a)
Solutions
- Swap the values so LimitBytes >= RequiredBytes in the volume's CapacityRange.
- If no maximum is intended, omit LimitBytes (set it to 0) and only specify RequiredBytes.
- Recheck units (GB vs GiB, MB vs MiB) and recompute both byte values consistently.
- Re-register or re-submit the volume/job spec with the corrected capacity range.
Example fix
// before
CapacityRange: &CSICapacityRange{
RequiredBytes: 10 * 1024 * 1024 * 1024,
LimitBytes: 5 * 1024 * 1024 * 1024,
}
// after
CapacityRange: &CSICapacityRange{
RequiredBytes: 5 * 1024 * 1024 * 1024,
LimitBytes: 10 * 1024 * 1024 * 1024,
} Defensive patterns
Strategy: validation
Validate before calling
func validateCapacityRange(required, limit int64) error {
if required == 0 && limit == 0 {
return fmt.Errorf("one of LimitBytes or RequiredBytes must be set")
}
if limit > 0 && limit < required {
return fmt.Errorf("LimitBytes (%d) must be >= RequiredBytes (%d)", limit, required)
}
return nil
} Type guard
func validCapacity(c *CSICapacityRange) bool {
return c == nil || (c.LimitBytes == 0 || c.LimitBytes >= c.RequiredBytes)
} Prevention
- Define capacity as (minimum, maximum) pairs in one config source to keep them consistent.
- Use explicit byte constants (GiB) to avoid GB/GiB confusion.
- Omit LimitBytes entirely when no cap is needed.
- Run a dry-run validation of volume specs in CI before deployment.
When it happens
Trigger: Calling NodePublishVolume (via a volume registration whose validate volume options path invokes Validate) with CapacityRange set to {RequiredBytes: 1073741824, LimitBytes: 536870912}. Note that if both RequiredBytes and LimitBytes are 0 the earlier 'one of LimitBytes or RequiredBytes must be set' error fires instead; this error only fires when LimitBytes > 0 and LimitBytes < RequiredBytes.
Common situations: Hand-editing a Nomad CSI volume spec and swapping the two numbers; templating tools that fill RequiredBytes from an environment value larger than a hard-coded LimitBytes; unit confusion (GB vs GiB) causing limit < required; copying an example spec and scaling required capacity upward without updating the limit.
Related errors
- CSI.ControllerAttachVolume: VolumeID is required
- CSI.ControllerAttachVolume: ClientCSINodeID is required
- CSI.ControllerDetachVolume: VolumeID is required
- CSI.ControllerDetachVolume: ClientCSINodeID is required
- CSI.NodeDetachVolume: PluginID is required
AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04).
Data as JSON: /api/errors/a7975dfbcb5ac850.
Report an issue: GitHub.