docker/cli · error

--userns: invalid USER mode

Error message

--userns: invalid USER mode

What it means

The Docker CLI validates the --userns flag value by converting it to container.UsernsMode and calling Valid() before building the HostConfig (cli/command/container/opts.go:528-531). Only recognized user-namespace modes are accepted; anything else aborts container creation client-side so an invalid mode never reaches the daemon.

Source

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

	// collect all the labels for the container
	labels, err := opts.ReadKVStrings(copts.labelsFile.GetSlice(), copts.labels.GetSlice())
	if err != nil {
		return nil, fmt.Errorf("--label-file: %w", err)
	}

	pidMode := container.PidMode(copts.pidMode)
	if !pidMode.Valid() {
		return nil, errors.New("--pid: invalid PID mode")
	}

	utsMode := container.UTSMode(copts.utsMode)
	if !utsMode.Valid() {
		return nil, errors.New("--uts: invalid UTS mode")
	}

	usernsMode := container.UsernsMode(copts.usernsMode)
	if !usernsMode.Valid() {
		return nil, errors.New("--userns: invalid USER mode")
	}

	cgroupnsMode := container.CgroupnsMode(copts.cgroupnsMode)
	if !cgroupnsMode.Valid() {
		return nil, errors.New("--cgroupns: invalid CGROUP mode")
	}

	restartPolicy, err := opts.ParseRestartPolicy(copts.restartPolicy)
	if err != nil {
		return nil, err
	}

	loggingOpts, err := parseLoggingOpts(copts.loggingDriver, copts.loggingOpts.GetSlice())
	if err != nil {
		return nil, err
	}

	securityOpts, err := parseSecurityOpts(copts.securityOpt.GetSlice())

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use `--userns=host` to disable user-namespace remapping for this container, or omit the flag entirely to use the daemon default
2. To enable remapping, configure the daemon with `userns-remap` in /etc/docker/daemon.json instead of a per-container flag
3. Check for typos or shell-quoting issues that leave an unexpected value in the flag

Example fix

# before
docker run --userns=private alpine
# after
docker run --userns=host alpine   # or omit --userns and configure userns-remap on the daemon

When it happens

Trigger: Running `docker run --userns=<value>` or `docker create --userns=<value>` where <value> is not one of the accepted modes: empty, `host`, or (in the API types' Valid() implementation) a container reference form. E.g. `docker run --userns=private` or `--userns=remap` fails at parse time in parse().

Common situations: Confusing daemon-level userns-remap configuration with the per-container --userns flag; typing `--userns=default` or `--userns=remap` expecting to opt into remapping (per-container you can only opt OUT with `host`); copy-pasting Kubernetes/Podman userns values (`auto`, `keep-id`) which Docker CLI does not accept.

Related errors

• --cgroupns: invalid CGROUP mode
• --pid: invalid PID mode
• --uts: invalid UTS mode
• --no-healthcheck conflicts with --health-* options
• --health-interval cannot be negative

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