docker/cli · error

invalid device specification

Error message

invalid device specification: %s

What it means

Thrown by parseLinuxDevice when the device string splits into 4 or more colon-separated parts (strings.SplitN with limit 4 returns len 4), exceeding the maximum of src[:dst[:mode]]. This means too many colons were supplied.

Solutions

1. Use at most two colons: --device /dev/sda1:/dev/sda1:rwm
2. Remove extra segments; a device spec has at most host[:container[:mode]]
3. Quote paths containing colons appropriately or avoid them

Example fix

# before
docker run --device /dev/loop0:/dev/loop0:rwm:extra ...
# after
docker run --device /dev/loop0:/dev/loop0:rwm ...

// Reject device specs with too many colon segments.
func validDeviceSpec(spec string) error {
    if strings.Count(spec, ":") > 2 {
        return fmt.Errorf("device spec %q has too many segments", spec)
    }
    return nil
}

When it happens

Trigger: Calling `docker run --device a:b:c:d` (three colons yields 4 parts). The expected formats are /dev/src, /dev/src:/dev/dst, or /dev/src:/dev/dst:rwm.

Common situations: Typing an extra colon; using a Windows-style path with a drive letter inside a Linux device spec (e.g. C:\... converted); copy-pasting a path containing colons; misunderstanding the three-field limit.

Related errors

• bad format for path
• got a device
• invalid --security-opt
• unknown server OS
• invalid device cgroup format

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

Appendix: source

Thrown at cli/command/container/opts.go:1028

	var src, dst string
	permissions := "rwm"
	// We expect 3 parts at maximum; limit to 4 parts to detect invalid options.
	arr := strings.SplitN(device, ":", 4)
	switch len(arr) {
	case 3:
		permissions = arr[2]
		fallthrough
	case 2:
		if validDeviceMode(arr[1]) {
			permissions = arr[1]
		} else {
			dst = arr[1]
		}
		fallthrough
	case 1:
		src = arr[0]
	default:
		return container.DeviceMapping{}, fmt.Errorf("invalid device specification: %s", device)
	}

	if dst == "" {
		dst = src
	}

	return container.DeviceMapping{
		PathOnHost:        src,
		PathInContainer:   dst,
		CgroupPermissions: permissions,
	}, nil
}

// validateDeviceCgroupRule validates a device cgroup rule string format
// It will make sure 'val' is in the form:
//
//	'type major:minor mode'
func validateDeviceCgroupRule(val string) (string, error) {

View on GitHub (pinned to 4f84911bfe)