docker/cli · error

unknown server OS

Error message

unknown server OS: %s

What it means

Thrown by parseDevice when the server OS type reported by the daemon is neither 'linux' nor 'windows'. The function switches on serverOS and only handles those two; any other value reaches the default case.

Solutions

1. Check the daemon: docker version and docker info to see the OS/Server info
2. Connect to a daemon whose OSType is linux or windows
3. Drop the --device flag if the target daemon does not support device mapping
4. Verify you are pointing at a real Docker/Moby daemon and not a proxy

// Confirm daemon OS before issuing device flags.
info, err := cli.ServerVersion(ctx)
if err != nil {
    return err
}
if info.Os != "linux" && info.Os != "windows" {
    return fmt.Errorf("unsupported daemon OS %q for --device", info.Os)
}

When it happens

Trigger: Passing --device while connected to a daemon whose Ping OSType returns something other than 'linux' or 'windows'. The OSType comes from the daemon's Ping response and is passed through from serverInfo.OSType.

Common situations: Connected to a daemon in an unsupported/unusual environment; a custom or buggy daemon returning an empty or non-standard OSType; version mismatch between an old/new client and daemon; connecting to a non-Docker API endpoint that partially answers Ping.

Related errors

• got a device
• invalid device specification
• invalid device cgroup format
• bad format for path
• bad mode specified

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

Appendix: source

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

		k, v, ok := strings.Cut(option, "=")
		if !ok {
			return nil, errors.New("invalid storage option")
		}
		m[k] = v
	}
	return m, nil
}

// parseDevice parses a device mapping string to a container.DeviceMapping struct
func parseDevice(device, serverOS string) (container.DeviceMapping, error) {
	switch serverOS {
	case "linux":
		return parseLinuxDevice(device)
	case "windows":
		// Windows doesn't support mapping, so passing the given value as-is.
		return container.DeviceMapping{PathOnHost: device}, nil
	default:
		return container.DeviceMapping{}, fmt.Errorf("unknown server OS: %s", serverOS)
	}
}

// parseLinuxDevice parses a device mapping string to a container.DeviceMapping struct
// knowing that the target is a Linux daemon
func parseLinuxDevice(device string) (container.DeviceMapping, error) {
	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 {

View on GitHub (pinned to 4f84911bfe)