docker/cli · error

--uts: invalid UTS mode

Error message

--uts: invalid UTS mode

What it means

Returned when the value passed to --uts fails container.UTSMode.Valid() (opts.go:523-526). Valid UTS modes are the empty string (default) or "host". Unlike --pid, container:<id> sharing is not supported for the UTS namespace, so any other value is rejected.

Solutions

1. Use `--uts=host` to share the host UTS namespace (hostname).
2. Omit the flag for the default private UTS namespace.
3. Remove any container:<id> form -- it is unsupported for --uts.

Example fix

// before
docker run --uts=container:webapp myimage
// after
docker run --uts=host myimage

if um := container.UTSMode(copts.utsMode); !um.Valid() {
    return fmt.Errorf("--uts: invalid UTS mode %q", copts.utsMode)
}

// isValidUtsMode narrows acceptable --uts values.
func isValidUtsMode(s string) bool {
    return s == "" || s == "host"
}

When it happens

Trigger: Running `docker run --uts=<bad> ...` with anything other than empty or "host". Common offenders: `--uts=container:foo`, `--uts=private`, `--uts=hosk`.

Common situations: Assuming --uts supports the same `container:<id>` syntax as --pid/--ipc; mistyping "host"; expecting a "private" keyword (private is the default, not a named value).

Related errors

• --pid: invalid PID 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/40799e3f5fbca4dc. Report an issue: GitHub.

Appendix: source

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

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

	loggingOpts, err := parseLoggingOpts(copts.loggingDriver, copts.loggingOpts.GetSlice())

View on GitHub (pinned to 4f84911bfe)