docker/cli · error

--uts: invalid UTS mode

Error message

--uts: invalid UTS mode

What it means

Immediately after the PID-mode check, the --uts flag value is wrapped in container.UTSMode and validated. UTSMode only accepts an empty value (default: private UTS namespace) or "host" (share the host's hostname/domainname namespace); any other value fails Valid() and the CLI rejects it before container creation.

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

Solutions

1. Use `--uts=host` to share the host UTS namespace, or omit the flag entirely for the default private namespace.
2. If you were trying to set the container hostname, use `--hostname=<name>` instead of --uts.
3. Fix typos in the flag value.

Example fix

# before
docker run --uts=private --hostname=web myimage
# after (private is the default; just set the hostname)
docker run --hostname=web myimage

When it happens

Trigger: `docker run --uts=<value>` with any value other than "host" or empty — e.g. `--uts=private`, `--uts=container:xyz` (not supported for UTS in the CLI), or a typo like `--uts=hsot`.

Common situations: Assuming --uts accepts `container:<id>` like --pid/--net do; carrying over `private` from other runtimes' syntax; typos of `host` in compose-generated or hand-written run commands.

Related errors

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