docker/cli · error

--pid: invalid PID mode

Error message

--pid: invalid PID mode

What it means

During parsing of run/create options, the value passed to --pid is wrapped in container.PidMode and checked with Valid(). PidMode only accepts an empty value, "host", or "container:<name|id>"; anything else fails validation and the CLI rejects the flag before creating the container.

Source

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

		}
		deviceMappings = append(deviceMappings, deviceMapping)
	}

	// collect all the environment variables for the container
	envVariables, err := opts.ReadKVEnvStrings(copts.envFile.GetSlice(), copts.env.GetSlice())
	if err != nil {
		return nil, fmt.Errorf("--env-file: %w", err)
	}

	// 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)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use one of the supported modes: `--pid=host` or `--pid=container:<name-or-id>`, or omit the flag for the default private PID namespace.
2. If using `container:<name>`, ensure the name/ID variable is non-empty and refers to an existing container.
3. Check for typos in the flag value.

Example fix

# before
docker run --pid=private myimage
# after (default is already a private PID namespace)
docker run myimage
# or share the host PID namespace
docker run --pid=host myimage

When it happens

Trigger: `docker run --pid=<value>` where value is not "", "host", or "container:<name|id>" — e.g. `--pid=private`, `--pid=container:` with an empty target, or a typo like `--pid=hots`.

Common situations: Typos of `host`; assuming Kubernetes/Podman-style values like `private` or `pod` work in Docker; scripts interpolating an empty container name into `container:$NAME` producing `container:`.

Related errors

• --uts: invalid UTS mode
• container ID file found, make sure the other container isn't
• --userns: invalid USER mode
• --cgroupns: invalid CGROUP mode
• --health-interval cannot be negative

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