nektos/act · error

invalid device specification: %s

Error message

invalid device specification: %s

What it means

parseLinuxDevice splits a --device specification (host[:container[:mode]]) using SplitN with a limit of 4. A valid spec yields 1-3 parts; hitting the default branch means 4 or more colon-separated segments were found, which cannot be a valid device mapping.

Source

Thrown at pkg/container/docker_cli.go:1035

	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 4f41128141)

Solutions

1. Count the colons: the spec must have at most three segments host:container:mode
2. Rewrite as --device /dev/foo:/dev/foo:rwm
3. Specify multiple devices with repeated --device flags instead of one string
4. For Windows paths on a Linux daemon, use POSIX-style device paths

Example fix

# before
--device /dev/bus/usb/001/001:/dev/bus/usb/001/001:rwm:oops

# after
--device /dev/bus/usb/001/001:/dev/bus/usb/001/001:rwm

// Go: reject device specs with more than 3 colon segments up front
func validDeviceShape(s string) bool { return strings.Count(s, ":") <= 2 }

When it happens

Trigger: Passing a device string with 4+ colon-separated parts, e.g. --device /dev/foo:/dev/foo:rwm:extra or a Windows-style path like C:\dev\x:/dev/x:rwm on a Linux daemon.

Common situations: Typos with extra colons, copy-pasting Windows paths into --device on Linux, or concatenating two device specs into one flag.

Related errors

• unknown server OS: %s
• invalid device cgroup format '%s'
• --pid: invalid PID mode
• invalid storage option
• valid streams are STDIN, STDOUT and STDERR

AI-assisted analysis of nektos/act@4f41128141 (2026-08-15). Data as JSON: /api/errors/467959427485d345. Report an issue: GitHub.