docker/cli · error

--userns: invalid USER mode

Error message

--userns: invalid USER mode

What it means

Returned when the value passed to --userns fails container.UsernsMode.Valid() (opts.go:528-531). Valid user-namespace modes are the empty string (default, which honors the daemon's user-namespace remap config) or "host" (run in the host user namespace, disabling remap). Any other keyword is rejected.

Solutions

1. Use `--userns=host` to disable user-namespace remapping for this container.
2. Omit the flag to use the daemon's default user-namespace mode.
3. Do not attempt container:<id> or named-profile values with --userns.

Example fix

// before
docker run --userns=remap myimage
// after
docker run --userns=host myimage

if un := container.UsernsMode(copts.usernsMode); !un.Valid() {
    return fmt.Errorf("--userns: invalid USER mode %q", copts.usernsMode)
}

// isValidUsernsMode narrows acceptable --userns values.
func isValidUsernsMode(s string) bool {
    return s == "" || s == "host"
}

When it happens

Trigger: Running `docker run --userns=<bad> ...` with a value that is neither empty nor "host". For example `--userns=private`, `--userns=remap`, `--userns=container:foo`.

Common situations: Confusing --userns with other namespace flags that accept container:<id>; assuming a named remap profile can be selected here (it cannot -- remapping is configured daemon-side); typos.

Related errors

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

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

Appendix: 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 4f84911bfe)