docker/cli · error

--pid: invalid PID mode

Error message

--pid: invalid PID mode

What it means

Returned when the value passed to --pid fails container.PidMode.Valid() (opts.go:518-521). Valid PID modes are the empty string (default/private), "host", or "container:<name-or-id>". Any malformed value (e.g. a typo, missing container: prefix, or unsupported keyword) is rejected before container creation.

Solutions

1. Use `--pid=host` to share the host PID namespace.
2. Use `--pid=container:<name|id>` to share another container's PID namespace.
3. Omit the flag to use the default private PID namespace.
4. Double-check for typos in the keyword.

Example fix

// before
docker run --pid=container: myimage
// after
docker run --pid=container:webapp myimage

// Validate the PID mode before invoking the client.
if pm := container.PidMode(copts.pidMode); !pm.Valid() {
    return fmt.Errorf("--pid: invalid PID mode %q", copts.pidMode)
}

// isValidPidMode narrows acceptable --pid values.
func isValidPidMode(s string) bool {
    return s == "" || s == "host" || strings.HasPrefix(s, "container:")
}

When it happens

Trigger: Running `docker run --pid=<bad> ...` where <bad> is not one of: empty, "host", or "container:<id>". For example `--pid=container:` (empty id), `--pid=shared`, `--pid=hosk`.

Common situations: Typing the namespace keyword incorrectly; forgetting the `container:` prefix when sharing a PID namespace; assuming `--pid=shared` or other cgroup-style keywords are supported.

Related errors

• --uts: invalid UTS mode
• --userns: invalid USER 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/6466fdd22e825c07. Report an issue: GitHub.

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