conflicting options: cannot specify both --timeout and…

Error message

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

What it means

Returned by the restart command when both --timeout and the deprecated --time are set on the same invocation. Both flags bind to the same timeout value, so providing both is ambiguous; the CLI explicitly checks cmd.Flags().Changed for both and rejects the combination. --time is kept only for backward compatibility and marked deprecated.

Solutions

Use only --timeout (the supported flag): `docker restart --timeout 10 ctr`.
Remove the deprecated --time from scripts and aliases.
If automating, normalize to --timeout in your flag builder before invoking docker.

Example fix

// before
docker restart --time 10 --timeout 20 ctr

// after
docker restart --timeout 10 ctr

Defensive patterns

Strategy: validation

Validate before calling

// Normalize to --timeout only before invoking restart.
func normalizeRestartTimeout(hasTime, hasTimeout bool) error {
    if hasTime && hasTimeout {
        return errors.New("conflicting options: cannot specify both --timeout and --time")
    }
    return nil
}

Prevention

Standardize all scripts on --timeout; remove --time.
In wrapper tools, never emit both flags; translate --time to --timeout once.
Add a lint rule that flags --time usage alongside --timeout.

When it happens

Trigger: `docker restart --time 10 --timeout 20 ctr`. Both flags present triggers the guard at restart.go:32-33.

Common situations: Old scripts using --time being gradually migrated to --timeout but both left in during transition. Wrapper scripts concatenating flags. Copy-pasting from two references that use different flags.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

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

type restartOptions struct {
	signal         string
	timeout        int
	timeoutChanged bool

	containers []string
}

// newRestartCommand creates a new cobra.Command for "docker container restart".
func newRestartCommand(dockerCLI command.Cli) *cobra.Command {
	var opts restartOptions

	cmd := &cobra.Command{
		Use:   "restart [OPTIONS] CONTAINER [CONTAINER...]",
		Short: "Restart one or more 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 runRestart(cmd.Context(), dockerCLI, &opts)
		},
		Annotations: map[string]string{
			"aliases": "docker container restart, docker restart",
		},
		ValidArgsFunction:     completion.ContainerNames(dockerCLI, true),
		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 4f84911bfe)