{"id":"3f91d97fc65d3a6b","repo":"docker/cli","slug":"userns-invalid-user-mode","errorCode":null,"errorMessage":"--userns: invalid USER mode","messagePattern":"--userns: invalid USER mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":530,"sourceCode":"\t// collect all the labels for the container\n\tlabels, err := opts.ReadKVStrings(copts.labelsFile.GetSlice(), copts.labels.GetSlice())\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"--label-file: %w\", err)\n\t}\n\n\tpidMode := container.PidMode(copts.pidMode)\n\tif !pidMode.Valid() {\n\t\treturn nil, errors.New(\"--pid: invalid PID mode\")\n\t}\n\n\tutsMode := container.UTSMode(copts.utsMode)\n\tif !utsMode.Valid() {\n\t\treturn nil, errors.New(\"--uts: invalid UTS mode\")\n\t}\n\n\tusernsMode := container.UsernsMode(copts.usernsMode)\n\tif !usernsMode.Valid() {\n\t\treturn nil, errors.New(\"--userns: invalid USER mode\")\n\t}\n\n\tcgroupnsMode := container.CgroupnsMode(copts.cgroupnsMode)\n\tif !cgroupnsMode.Valid() {\n\t\treturn nil, errors.New(\"--cgroupns: invalid CGROUP mode\")\n\t}\n\n\trestartPolicy, err := opts.ParseRestartPolicy(copts.restartPolicy)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tloggingOpts, err := parseLoggingOpts(copts.loggingDriver, copts.loggingOpts.GetSlice())\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tsecurityOpts, err := parseSecurityOpts(copts.securityOpt.GetSlice())","sourceCodeStart":512,"sourceCodeEnd":548,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/container/opts.go#L512-L548","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Use `--userns=host` to disable user-namespace remapping for this container, or omit the flag entirely to use the daemon default","To enable remapping, configure the daemon with `userns-remap` in /etc/docker/daemon.json instead of a per-container flag","Check for typos or shell-quoting issues that leave an unexpected value in the flag"],"exampleFix":"# before\ndocker run --userns=private alpine\n# after\ndocker run --userns=host alpine   # or omit --userns and configure userns-remap on the daemon","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","user-namespace","flag-validation","container-create"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}