{"record":{"id":"f67b5fd6e6223495","repo":"docker/cli","slug":"invalid-rate-for-device-s-the-correct-format-is","errorCode":null,"errorMessage":"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","messagePattern":"invalid rate for device: (.+?)\\. The correct format is <device-path>:<number>\\[<unit>\\]\\. Number must be a positive integer\\. Unit is optional and can be kb, mb, or gb","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"opts/throttledevice.go","lineNumber":27,"sourceCode":"\t\"github.com/moby/moby/api/types/blkiodev\"\n)\n\n// ValidatorThrottleFctType defines a validator function that returns a validated struct and/or an error.\ntype ValidatorThrottleFctType func(val string) (*blkiodev.ThrottleDevice, error)\n\n// ValidateThrottleBpsDevice validates that the specified string has a valid device-rate format.\nfunc ValidateThrottleBpsDevice(val string) (*blkiodev.ThrottleDevice, error) {\n\tk, v, ok := strings.Cut(val, \":\")\n\tif !ok || k == \"\" {\n\t\treturn nil, fmt.Errorf(\"bad format: %s\", val)\n\t}\n\t// TODO(thaJeztah): should we really validate this on the client?\n\tif !strings.HasPrefix(k, \"/dev/\") {\n\t\treturn nil, fmt.Errorf(\"bad format for device path: %s\", val)\n\t}\n\trate, err := units.RAMInBytes(v)\n\tif err != nil {\n\t\treturn 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)\n\t}\n\tif rate < 0 {\n\t\treturn 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)\n\t}\n\n\treturn &blkiodev.ThrottleDevice{\n\t\tPath: k,\n\t\tRate: uint64(rate),\n\t}, nil\n}\n\n// ValidateThrottleIOpsDevice validates that the specified string has a valid device-rate format.\nfunc ValidateThrottleIOpsDevice(val string) (*blkiodev.ThrottleDevice, error) {\n\tk, v, ok := strings.Cut(val, \":\")\n\tif !ok || k == \"\" {\n\t\treturn nil, fmt.Errorf(\"bad format: %s\", val)\n\t}\n\t// TODO(thaJeztah): should we really validate this on the client?","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/opts/throttledevice.go#L9-L45","documentation":"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.","triggerScenarios":"'docker run --device-read-bps=/dev/sda:abc', '...=/dev/sda:1xb', '...=/dev/sda:1.5mb' (floats are not accepted), or '...=/dev/sda:' (empty rate).","commonSituations":"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.","solutions":["Use a positive integer with an optional kb/mb/gb suffix: '/dev/sda:1mb' or a bare byte count '/dev/sda:1048576'.","Remove decimal points; RAMInBytes does not accept floats.","Use only the supported lowercase suffixes kb, mb, gb (or k/m/g)."],"exampleFix":"# before\ndocker run --device-read-bps=/dev/sda:1.5mb ubuntu\n# after\ndocker run --device-read-bps=/dev/sda:2mb ubuntu","handlingStrategy":"validation","validationCode":"// Pre-parse the rate with the same units the validator uses (go-units RAMInBytes).\nimport \"github.com/docker/go-units\"\n\nfunc validBpsRate(s string) bool {\n    _, v, ok := strings.Cut(s, \":\")\n    if !ok || v == \"\" { return false }\n    n, err := units.RAMInBytes(v)\n    return err == nil && n >= 0\n}\n\n// if !validBpsRate(val) { return fmt.Errorf(\"rate must be <int>[kb|mb|gb], got %q\", val) }","typeGuard":null,"tryCatchPattern":"if _, err := opts.ValidateThrottleBpsDevice(val); err != nil {\n    return err // invalid rate for device: <val> ...\n}","preventionTips":["Use only integer values with optional kb/mb/gb suffixes.","Avoid fractional rates (RAMInBytes rejects floats).","Avoid IEC units (kib/mib/gib) — only kb/mb/gb are accepted."],"tags":["docker","blkio","throttle","units","cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}