docker/cli · error

bad format for path

Error message

bad format for path: %s

What it means

Thrown by validateLinuxPath when the device/path string contains more than two colons (strings.Count(val, ":") > 2). The accepted format [host:]container[:mode] allows at most two colons.

Solutions

1. Reduce to at most two colons: host:container:mode
2. Drop the extra segment

Example fix

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

func validPathColonCount(spec string) error {
    if strings.Count(spec, ":") > 2 {
        return fmt.Errorf("path %q has too many colons", spec)
    }
    return nil
}

When it happens

Trigger: Passing a --device or path spec with three or more colons, e.g. '/a:/b:/c:/d'. This is checked before the split.

Common situations: Extra colon from a typo; concatenating host:container:mode with an additional stray separator; Windows paths leaking colons into Linux specs.

Related errors

• invalid device specification
• is not an absolute path
• got a device
• unknown server OS
• invalid device cgroup format

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

Appendix: source

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

		// Windows does validation entirely server-side
		return val, nil
	}
	return "", fmt.Errorf("unknown server OS: %s", serverOS)
}

// validateLinuxPath is the implementation of validateDevice knowing that the
// target server operating system is a Linux daemon.
// It will make sure 'val' is in the form:
//
//	[host-dir:]container-path[:mode]
//
// It also validates the device mode.
func validateLinuxPath(val string, validator func(string) bool) (string, error) {
	var containerPath string
	var mode string

	if strings.Count(val, ":") > 2 {
		return val, fmt.Errorf("bad format for path: %s", val)
	}

	split := strings.SplitN(val, ":", 3)
	if split[0] == "" {
		return val, fmt.Errorf("bad format for path: %s", val)
	}
	switch len(split) {
	case 1:
		containerPath = split[0]
		val = path.Clean(containerPath)
	case 2:
		if isValid := validator(split[1]); isValid {
			containerPath = split[0]
			mode = split[1]
			val = fmt.Sprintf("%s:%s", path.Clean(containerPath), mode)
		} else {
			containerPath = split[1]
			val = fmt.Sprintf("%s:%s", split[0], path.Clean(containerPath))

View on GitHub (pinned to 4f84911bfe)