docker/cli · error

--cgroupns: invalid CGROUP mode

Error message

--cgroupns: invalid CGROUP mode

What it means

The CLI converts the --cgroupns flag to container.CgroupnsMode and rejects the command if Valid() fails (cli/command/container/opts.go:533-536). Valid cgroup-namespace modes are only empty, `host`, and `private`; validation happens client-side before the create request is sent.

Source

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

	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())
	if err != nil {
		return nil, err
	}

	securityOpts, maskedPaths, readonlyPaths := parseSystemPaths(securityOpts)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use `--cgroupns=private` or `--cgroupns=host` — these are the only accepted values
2. Omit the flag to use the daemon default (private on cgroup v2, host on cgroup v1)
3. Fix any typo or variable expansion producing an unexpected value

Example fix

# before
docker run --cgroupns=none alpine
# after
docker run --cgroupns=private alpine

When it happens

Trigger: `docker run --cgroupns=<value>` or `docker create --cgroupns=<value>` with any value other than `host`, `private`, or empty — e.g. `--cgroupns=none`, `--cgroupns=container:<id>`, or a typo like `--cgroupns=privte`.

Common situations: Assuming --cgroupns supports container: syntax like --pid/--network do (it does not); scripts written for Podman which accepts additional values; typos in compose-generated or templated run commands.

Related errors

• --userns: invalid USER 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/35345089aaf2c661.json. Report an issue: GitHub.