What causes "negative timeout %d is invalid" in docker/cli?

Use a non-negative timeout (0 is accepted and means use the default/no explicit limit).

negative timeout is invalid

Error message

negative timeout %d is invalid

What it means

Returned by runEnable (plugin/enable.go:39) when the --timeout flag is a negative integer. The timeout governs the HTTP client timeout passed to PluginEnable, so a negative value is meaningless and is rejected before any API call. The guard is a simple `opts.Timeout < 0` check.

Solutions

Use a non-negative timeout (0 is accepted and means use the default/no explicit limit).
Clamp computed timeout values with something like `max(0, computed)`.
Omit --timeout to keep the default of 30 seconds.

Example fix

// before
docker plugin enable --timeout $((START-END)) PLUGIN   # may be negative
// after
t=$(( START - END )); [ "$t" -lt 0 ] && t=0; docker plugin enable --timeout "$t" PLUGIN

Defensive patterns

Strategy: validation

Validate before calling

// Clamp the timeout before calling enable.
func sanitizeTimeout(t int) int {
    if t < 0 { return 0 }
    return t
}

Type guard

// isNonNegTimeout narrows ints that are valid enable timeouts.
func isNonNegTimeout(t int) bool { return t >= 0 }

Prevention

Clamp arithmetic results with max(0, value).
Use 0 or omit --timeout when you want the default.
Validate env-var-sourced timeouts before passing them through.

When it happens

Trigger: Running `docker plugin enable --timeout -1 PLUGIN` (or any negative value), typically from a script computing the timeout arithmetically and underflowing to a negative number.

Common situations: Shell arithmetic that subtracts more than intended, a misconfigured environment variable parsed as a negative int, or passing 0 thinking it means 'no timeout' then negating it.

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/4b8cc94d538ff61c. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/plugin/enable.go:39

			name := args[0]
			if err := runEnable(cmd.Context(), dockerCLI, name, opts); err != nil {
				return err
			}
			_, _ = fmt.Fprintln(dockerCLI.Out(), name)
			return nil
		},
		ValidArgsFunction:     completeNames(dockerCLI, stateDisabled),
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()
	flags.IntVar(&opts.Timeout, "timeout", 30, "HTTP client timeout (in seconds)")
	return cmd
}

func runEnable(ctx context.Context, dockerCli command.Cli, name string, opts client.PluginEnableOptions) error {
	if opts.Timeout < 0 {
		return fmt.Errorf("negative timeout %d is invalid", opts.Timeout)
	}
	_, err := dockerCli.Client().PluginEnable(ctx, name, opts)
	return err
}

View on GitHub (pinned to 4f84911bfe)