docker/cli · error

bad format for device path

Error message

bad format for device path: %s

What it means

Returned by ValidateWeightDevice when the device-path portion of a --blkio-weight-device value does not start with '/dev/'. Client-side prefix enforcement shared with the throttle validators.

Solutions

1. Use the full /dev path: '--blkio-weight-device=/dev/sda:200'.
2. Verify the node with 'lsblk' / 'ls /dev' before passing it.
3. Keep the /dev/ prefix for nvme, dm-, md, etc.

Example fix

# before
docker run --blkio-weight-device=sda:200 ubuntu
# after
docker run --blkio-weight-device=/dev/sda:200 ubuntu

// Enforce the /dev/ prefix the weight validator requires.
import "strings"

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

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

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

When it happens

Trigger: 'docker run --blkio-weight-device=sda:200' or '...=dev/sda:200' — key lacks the '/dev/' prefix.

Common situations: Passing a bare device name or sysfs path instead of the /dev node.

Related errors

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

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

Appendix: source

Thrown at opts/weightdevice.go:22

	"fmt"
	"strconv"
	"strings"

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

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

// ValidateWeightDevice validates that the specified string has a valid device-weight format.
func ValidateWeightDevice(val string) (*blkiodev.WeightDevice, 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)
	}
	weight, err := strconv.ParseUint(v, 10, 16)
	if err != nil {
		return nil, fmt.Errorf("invalid weight for device: %s", val)
	}
	if weight > 0 && (weight < 10 || weight > 1000) {
		return nil, fmt.Errorf("invalid weight for device: %s", val)
	}

	return &blkiodev.WeightDevice{
		Path:   k,
		Weight: uint16(weight),
	}, nil
}

// WeightdeviceOpt defines a map of WeightDevices
type WeightdeviceOpt struct {
	values    []*blkiodev.WeightDevice

View on GitHub (pinned to 4f84911bfe)