docker/cli · error

invalid rate for device

Error message

invalid rate for device: %s. The correct format is <device-path>:<number>. Number must be a positive integer

What it means

Returned by ValidateThrottleIOpsDevice when strconv.ParseUint(v, 10, 64) fails on the rate part of a --device-read-iops / --device-write-iops value. The iops rate MUST be a base-10 positive integer — no unit suffix, no decimal, no sign.

Solutions

1. Use a plain positive integer: '--device-read-iops=/dev/sda:1000'.
2. Drop any unit suffix — iops is a unitless count per second.
3. Ensure substituted values are digits only (strip suffixes/non-digits).

Example fix

# before
docker run --device-read-iops=/dev/sda:1mb ubuntu
# after
docker run --device-read-iops=/dev/sda:1000 ubuntu

// iops rate must be a base-10 unsigned integer (no unit) — check before validating.
import ("strconv"; "strings")

func validIops(s string) bool {
    _, v, ok := strings.Cut(s, ":")
    if !ok { return false }
    _, err := strconv.ParseUint(v, 10, 64)
    return err == nil
}

// if !validIops(val) { return fmt.Errorf("iops must be a positive integer, got %q", val) }

if _, err := opts.ValidateThrottleIOpsDevice(val); err != nil {
    return err // invalid rate for device: <val> ...
}

When it happens

Trigger: 'docker run --device-read-iops=/dev/sda:1mb' (most common: copying a bps-style unit suffix onto an iops flag), '...=/dev/sda:1.5k', '...=/dev/sda:-100', '...=/dev/sda:' (empty), or any non-numeric value.

Common situations: Users assume iops flags accept the same kb/mb/gb suffixes as the bps flags; they do not. Also triggered by env-var substitution that injects a suffix or empty string.

Related errors

• bad format
• bad format for device path
• invalid rate for device
• bad format
• bad format for device path

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/a1f58cb680a513a6. Report an issue: GitHub.

Appendix: source

Thrown at opts/throttledevice.go:51

	return &blkiodev.ThrottleDevice{
		Path: k,
		Rate: uint64(rate),
	}, nil
}

// ValidateThrottleIOpsDevice validates that the specified string has a valid device-rate format.
func ValidateThrottleIOpsDevice(val string) (*blkiodev.ThrottleDevice, error) {
	k, v, ok := strings.Cut(val, ":")
	if !ok || k == "" {
		return nil, fmt.Errorf("bad format: %s", val)
	}
	// TODO(thaJeztah): should we really validate this on the client?
	if !strings.HasPrefix(k, "/dev/") {
		return nil, fmt.Errorf("bad format for device path: %s", val)
	}
	rate, err := strconv.ParseUint(v, 10, 64)
	if err != nil {
		return nil, fmt.Errorf("invalid rate for device: %s. The correct format is <device-path>:<number>. Number must be a positive integer", val)
	}

	return &blkiodev.ThrottleDevice{Path: k, Rate: rate}, nil
}

// ThrottledeviceOpt defines a map of ThrottleDevices
type ThrottledeviceOpt struct {
	values    []*blkiodev.ThrottleDevice
	validator ValidatorThrottleFctType
}

// NewThrottledeviceOpt creates a new ThrottledeviceOpt
func NewThrottledeviceOpt(validator ValidatorThrottleFctType) ThrottledeviceOpt {
	return ThrottledeviceOpt{
		values:    []*blkiodev.ThrottleDevice{},
		validator: validator,
	}
}

View on GitHub (pinned to 4f84911bfe)