docker/cli · error

--health-timeout cannot be negative

Error message

--health-timeout cannot be negative

What it means

The CLI validates that --health-timeout, the maximum time a single health probe may run before being considered failed, is not negative (opts.go:581-583). Like the other health durations it is a time.Duration where 0 means 'daemon default', so negative values are rejected client-side.

Source

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

		copts.healthTimeout != 0 ||
		copts.healthStartPeriod != 0 ||
		copts.healthRetries != 0 ||
		copts.healthStartInterval != 0
	if copts.noHealthcheck {
		if haveHealthSettings {
			return nil, errors.New("--no-healthcheck conflicts with --health-* options")
		}
		healthConfig = &container.HealthConfig{Test: []string{"NONE"}}
	} else if haveHealthSettings {
		var probe []string
		if copts.healthCmd != "" {
			probe = []string{"CMD-SHELL", copts.healthCmd}
		}
		if copts.healthInterval < 0 {
			return nil, errors.New("--health-interval cannot be negative")
		}
		if copts.healthTimeout < 0 {
			return nil, errors.New("--health-timeout cannot be negative")
		}
		if copts.healthRetries < 0 {
			return nil, errors.New("--health-retries cannot be negative")
		}
		if copts.healthStartPeriod < 0 {
			return nil, errors.New("--health-start-period cannot be negative")
		}
		if copts.healthStartInterval < 0 {
			return nil, errors.New("--health-start-interval cannot be negative")
		}

		healthConfig = &container.HealthConfig{
			Test:          probe,
			Interval:      copts.healthInterval,
			Timeout:       copts.healthTimeout,
			StartPeriod:   copts.healthStartPeriod,
			StartInterval: copts.healthStartInterval,
			Retries:       copts.healthRetries,

View on GitHub (pinned to e9452d6e78)

Solutions

1. Provide a positive timeout, e.g. --health-timeout=5s
2. Omit the flag or pass 0 to use the default timeout
3. For a very long probe, set a large positive value instead of a negative sentinel

Example fix

# before
docker run --health-cmd 'curl -f localhost' --health-timeout=-1s myimage
# after
docker run --health-cmd 'curl -f localhost' --health-timeout=30s myimage

When it happens

Trigger: `docker run --health-cmd '...' --health-timeout=-1s image`, or any run/create where a health flag is set and the timeout duration parses negative (e.g. from an environment-variable expansion).

Common situations: Using -1 to try to mean 'no timeout'; arithmetic in wrapper scripts producing negative durations; confusion with APIs where -1 is a sentinel.

Related errors

• --health-interval cannot be negative
• --health-start-period cannot be negative
• --health-start-interval cannot be negative
• --health-retries cannot be negative
• --pid: invalid PID mode

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