docker/cli · error

--cgroupns: invalid CGROUP mode

Error message

--cgroupns: invalid CGROUP mode

What it means

Returned when the value passed to --cgroupns fails container.CgroupnsMode.Valid() (opts.go:533-536). Valid values are empty (use the daemon default-cgroupns-mode), "host" (run in the host cgroup namespace), or "private" (run in a private cgroup namespace). The flag requires API version >= 1.41. Any other value is rejected.

Solutions

1. Use `--cgroupns=host` or `--cgroupns=private` explicitly.
2. Omit the flag to inherit the daemon's default-cgroupns-mode.
3. Ensure the daemon supports API version 1.41+ (check `docker version`).

Example fix

// before
docker run --cgroupns=shared myimage
// after
docker run --cgroupns=private myimage

if cm := container.CgroupnsMode(copts.cgroupnsMode); !cm.Valid() {
    return fmt.Errorf("--cgroupns: invalid CGROUP mode %q", copts.cgroupnsMode)
}

// isValidCgroupnsMode narrows acceptable --cgroupns values.
func isValidCgroupnsMode(s string) bool {
    return s == "" || s == "host" || s == "private"
}

When it happens

Trigger: Running `docker run --cgroupns=<bad> ...` with a value other than empty, "host", or "private". For example `--cgroupns=container:foo`, `--cgroupns=none`, `--cgroupns=shared`.

Common situations: Using container:<id> syntax (unsupported for cgroupns); guessing keywords like "none"/"shared"; running against a daemon older than 1.41 that ignores or mishandles the flag.

Related errors

• --pid: invalid PID mode
• --uts: invalid UTS mode
• --userns: invalid USER mode
• --health-start-period cannot be negative
• --health-start-interval cannot be negative

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

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