docker/cli · error

--health-interval cannot be negative

Error message

--health-interval cannot be negative

What it means

When health settings are provided, the CLI rejects a negative --health-interval before building the container.HealthConfig (opts.go:578-580). The interval is a Go time.Duration controlling how often the health probe runs; a negative duration is meaningless, and 0 is reserved to mean 'use the daemon default'.

Source

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

	var healthConfig *container.HealthConfig
	haveHealthSettings := copts.healthCmd != "" ||
		copts.healthInterval != 0 ||
		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,

View on GitHub (pinned to e9452d6e78)

Solutions

1. Set a positive duration, e.g. --health-interval=30s
2. Omit the flag (or pass 0) to use the default interval
3. Use --no-healthcheck if the goal is to disable health probing

Example fix

# before
docker run --health-cmd 'curl -f localhost' --health-interval=-10s myimage
# after
docker run --health-cmd 'curl -f localhost' --health-interval=10s myimage

When it happens

Trigger: `docker run --health-cmd '...' --health-interval=-5s image` or any create/run where the parsed duration is negative, e.g. a templated value like --health-interval=${INTERVAL} expanding to a negative duration.

Common situations: Computed durations in scripts going negative; attempting to use -1 to mean 'disable' (use --no-healthcheck instead); unit typos producing negative values.

Related errors

• --health-timeout 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/1a45d9c1bdcd673d.json. Report an issue: GitHub.