docker/cli · error

invalid rate for device

Error message

invalid rate for device: %s. The correct format is <device-path>:<number>[<unit>]. Number must be a positive integer. Unit is optional and can be kb, mb, or gb

What it means

Returned by ValidateThrottleBpsDevice when units.RAMInBytes(v) fails to parse the rate portion (right of ':') of a --device-read-bps / --device-write-bps value. RAMInBytes accepts plain integers and the kb/mb/gb (and k/m/g) suffixes; anything else errors.

Solutions

1. Use a positive integer with an optional kb/mb/gb suffix: '/dev/sda:1mb' or a bare byte count '/dev/sda:1048576'.
2. Remove decimal points; RAMInBytes does not accept floats.
3. Use only the supported lowercase suffixes kb, mb, gb (or k/m/g).

Example fix

# before
docker run --device-read-bps=/dev/sda:1.5mb ubuntu
# after
docker run --device-read-bps=/dev/sda:2mb ubuntu

// Pre-parse the rate with the same units the validator uses (go-units RAMInBytes).
import "github.com/docker/go-units"

func validBpsRate(s string) bool {
    _, v, ok := strings.Cut(s, ":")
    if !ok || v == "" { return false }
    n, err := units.RAMInBytes(v)
    return err == nil && n >= 0
}

// if !validBpsRate(val) { return fmt.Errorf("rate must be <int>[kb|mb|gb], got %q", val) }

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

When it happens

Trigger: 'docker run --device-read-bps=/dev/sda:abc', '...=/dev/sda:1xb', '...=/dev/sda:1.5mb' (floats are not accepted), or '...=/dev/sda:' (empty rate).

Common situations: Using an unsupported unit ('1gib', '1kib'), a fractional rate, or a typo in the suffix; copying a rate from a tool that uses IEC units.

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/f67b5fd6e6223495. Report an issue: GitHub.

Appendix: source

Thrown at opts/throttledevice.go:27

	"github.com/moby/moby/api/types/blkiodev"
)

// ValidatorThrottleFctType defines a validator function that returns a validated struct and/or an error.
type ValidatorThrottleFctType func(val string) (*blkiodev.ThrottleDevice, error)

// ValidateThrottleBpsDevice validates that the specified string has a valid device-rate format.
func ValidateThrottleBpsDevice(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 := units.RAMInBytes(v)
	if err != nil {
		return nil, fmt.Errorf("invalid rate for device: %s. The correct format is <device-path>:<number>[<unit>]. Number must be a positive integer. Unit is optional and can be kb, mb, or gb", val)
	}
	if rate < 0 {
		return nil, fmt.Errorf("invalid rate for device: %s. The correct format is <device-path>:<number>[<unit>]. Number must be a positive integer. Unit is optional and can be kb, mb, or gb", val)
	}

	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?

View on GitHub (pinned to 4f84911bfe)