conflicting options: cannot specify both --restart and --rm

Error message

conflicting options: cannot specify both --restart and --rm

What it means

Returned when --rm (autoRemove) is enabled alongside a restart policy that is not "no" (opts.go:715-717). The default restart policy is RestartPolicyDisabled ("no"), so --rm alone is fine. The conflict arises because --rm deletes the container on exit while a restart policy (unless "no") would keep restarting it, making the two mutually exclusive. hostConfig.RestartPolicy.IsNone() is the discriminator.

Solutions

Remove --rm if you want the container auto-restarted.
Use --restart=no (or omit --restart, since "no" is the default) if you want --rm behavior.
Switch to --restart=unless-stopped and manage lifecycle externally instead of --rm.

Example fix

// before
docker run --rm --restart=always myimage
// after (auto-remove, no restart)
docker run --rm myimage
// after (auto-restart, no remove)
docker run --restart=always myimage

Defensive patterns

Strategy: validation

Validate before calling

// Disallow --rm with any non-"no" restart policy up front.
if copts.autoRemove && !container.RestartPolicyMode(copts.restartPolicy).IsNone() {
    return errors.New("conflicting options: cannot specify both --restart and --rm")
}

Type guard

// isNoneRestart reports whether the policy is the "no" default.
func isNoneRestart(policy string) bool {
    return policy == "" || policy == "no"
}

Prevention

Treat --rm and --restart (except no) as mutually exclusive in templates.
Default --restart to "no" so --rm composes cleanly.
Lint compose files for restart + auto_remove conflict.

When it happens

Trigger: Running `docker run --rm --restart=always ...` or `--rm --restart=on-failure ...` or `--rm --restart=unless-stopped ...`. Any restart policy except "no" combined with --rm triggers it.

Common situations: Copy-pasting flags from a long-running template and adding --rm for cleanup; wrapping `docker run` in a retry script that also sets --restart; misreading --restart=no (allowed) vs other policies.

Related errors

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

Appendix: source

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

		SecurityOpt:    securityOpts,
		StorageOpt:     storageOpts,
		ReadonlyRootfs: copts.readonlyRootfs,
		LogConfig:      container.LogConfig{Type: copts.loggingDriver, Config: loggingOpts},
		VolumeDriver:   copts.volumeDriver,
		Isolation:      container.Isolation(copts.isolation),
		ShmSize:        copts.shmSize.Value(),
		Resources:      resources,
		Tmpfs:          tmpfs,
		Sysctls:        copts.sysctls.GetAll(),
		Runtime:        copts.runtime,
		Mounts:         copts.mounts.Value(),
		MaskedPaths:    maskedPaths,
		ReadonlyPaths:  readonlyPaths,
		Annotations:    copts.annotations.GetAll(),
	}

	if copts.autoRemove && !hostConfig.RestartPolicy.IsNone() {
		return nil, errors.New("conflicting options: cannot specify both --restart and --rm")
	}

	// only set this value if the user provided the flag, else it should default to nil
	if flags.Changed("init") {
		hostConfig.Init = &copts.init
	}

	// When allocating stdin in attached mode, close stdin at client disconnect
	if config.OpenStdin && config.AttachStdin {
		config.StdinOnce = true
	}

	epCfg, err := parseNetworkOpts(copts)
	if err != nil {
		return nil, err
	}

	return &containerConfig{

View on GitHub (pinned to 4f84911bfe)