docker/cli · error

bad format for device path

Error message

bad format for device path: %s

What it means

Returned by ValidateThrottleBpsDevice when the device-path portion of a --device-read-bps / --device-write-bps value does not start with '/dev/'. The client enforces that device paths reference a /dev node even though the daemon could validate later.

Solutions

1. Use the full /dev path: '--device-read-bps=/dev/sda:1mb'.
2. If unsure of the node, list devices with 'ls /dev' or 'lsblk' and copy the /dev/<name> path.
3. Keep the /dev/ prefix even for NVMe/DM names (e.g. /dev/nvme0n1).

Example fix

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

// Enforce the /dev/ prefix the client requires, before calling the validator.
import "strings"

func hasDevPrefix(s string) bool {
    k, _, ok := strings.Cut(s, ":")
    return ok && strings.HasPrefix(k, "/dev/")
}

// if !hasDevPrefix(val) { return fmt.Errorf("device path must start with /dev/: %q", val) }

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

When it happens

Trigger: 'docker run --device-read-bps=sda:1mb' or '...=dev/sda:1mb' or '...=/sys/block/sda:1mb' — anything whose left-of-colon key lacks the literal '/dev/' prefix.

Common situations: Users pass a bare device name ('sda') or a sysfs path instead of a /dev node, assuming Docker resolves the shorthand.

Related errors

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

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

Appendix: source

Thrown at opts/throttledevice.go:23

	"strconv"
	"strings"

	"github.com/docker/go-units"
	"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, ":")

View on GitHub (pinned to 4f84911bfe)