What causes "--health-retries cannot be negative" in docker/cli?

Use a non-negative integer like --health-retries=3.

--health-retries cannot be negative

Error message

--health-retries cannot be negative

What it means

Returned when --health-retries is set to a negative integer (opts.go:584-586). The flag is registered with flags.IntVar (opts.go:265), so values like -3 parse successfully. A negative consecutive-failure count is meaningless and rejected inside the haveHealthSettings branch.

Solutions

Use a non-negative integer like --health-retries=3.
Use 0 (or omit) for the daemon default.
Do not use -1; it is not special for health-retries.

Example fix

// before
docker run --health-retries=-1 --health-cmd=/check.sh myimage
// after
docker run --health-retries=3 --health-cmd=/check.sh myimage

Defensive patterns

Strategy: validation

Validate before calling

if copts.healthRetries < 0 {
    return errors.New("--health-retries cannot be negative")
}

Prevention

Clamp retries to >= 0 in config generators.
Remember -1 is NOT unlimited here (unlike --pids-limit).
Validate integer inputs before runtime.

When it happens

Trigger: Running `docker run --health-retries=-3 ...` or any negative int, while health settings are present. Triggered by a literal negative value or a negative variable.

Common situations: Shell/compose variable resolving to a negative number; arithmetic bug computing retries; confusion with flags like --pids-limit that treat -1 as unlimited (health-retries has no such convention).

Related errors

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

Appendix: source

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

		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 4f84911bfe)