docker/cli · error

conflicting options: cannot specify both --timeout and --tim

Error message

conflicting options: cannot specify both --timeout and --time

What it means

The docker CLI's `docker container stop` command accepts both --timeout (current) and --time (deprecated alias); both flags write to the same stopOptions.timeout field. The RunE handler checks cmd.Flags().Changed for each and rejects the invocation if the user set both, because there would be no deterministic winner for the shutdown grace period.

Source

Thrown at cli/command/container/stop.go:33

type stopOptions struct {
	signal         string
	timeout        int
	timeoutChanged bool

	containers []string
}

// newStopCommand creates a new cobra.Command for "docker container stop".
func newStopCommand(dockerCLI command.Cli) *cobra.Command {
	var opts stopOptions

	cmd := &cobra.Command{
		Use:   "stop [OPTIONS] CONTAINER [CONTAINER...]",
		Short: "Stop one or more running containers",
		Args:  cli.RequiresMinArgs(1),
		RunE: func(cmd *cobra.Command, args []string) error {
			if cmd.Flags().Changed("time") && cmd.Flags().Changed("timeout") {
				return errors.New("conflicting options: cannot specify both --timeout and --time")
			}
			opts.containers = args
			opts.timeoutChanged = cmd.Flags().Changed("timeout") || cmd.Flags().Changed("time")
			return runStop(cmd.Context(), dockerCLI, &opts)
		},
		Annotations: map[string]string{
			"aliases": "docker container stop, docker stop",
		},
		ValidArgsFunction:     completion.ContainerNames(dockerCLI, false),
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()
	flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
	flags.IntVarP(&opts.timeout, "timeout", "t", 0, "Seconds to wait before killing the container")

	// The --time option is deprecated, but kept for backward compatibility.
	flags.IntVar(&opts.timeout, "time", 0, "Seconds to wait before killing the container (deprecated: use --timeout)")

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use only --timeout (or -t): `docker stop --timeout 10 <container>`.
2. Remove the deprecated --time flag from scripts and aliases; it maps to the same value and is slated for removal.
3. Audit shell wrappers/CI templates for both flag spellings and standardize on --timeout.

Example fix

# before
docker stop --time 5 --timeout 10 mycontainer
# after
docker stop --timeout 10 mycontainer

When it happens

Trigger: Running `docker stop --time 5 --timeout 10 <container>` (or `docker container stop`) with both flags explicitly set on the command line, in any order and even with identical values. Setting only one of the two flags never triggers it.

Common situations: Shell aliases or wrapper scripts written for older Docker versions that inject --time, combined with a user adding --timeout manually; CI pipelines migrating to the new flag name while an old flag remains in a shared script fragment; copy-pasting examples from docs of different Docker versions.

Related errors

• conflicting options: cannot specify both --timeout and --tim
• you must provide one or more flags when using this command
• conflicting options: cannot specify both --host and --contex
• conflicting options: --no-pause and --pause cannot be used t
• conflicting options: cannot specify both --network-alias and

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