docker/cli · error

invalid device specification: %s

Error message

invalid device specification: %s

What it means

Error "invalid device specification: %s" thrown in docker/cli.

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 e9452d6e78)

When it happens

Trigger: Thrown at cli/command/container/opts.go:1028 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/d524ab47ff9e144e.json. Report an issue: GitHub.