docker/cli · error

--health-interval cannot be negative

Error message

--health-interval cannot be negative

What it means

Returned when --health-interval is set to a negative duration (opts.go:578-580). The flag is registered with flags.DurationVar (opts.go:264), so Go's duration parser accepts values like "-5s". A negative interval between health checks is nonsensical, so it is rejected only when haveHealthSettings is true.

Solutions

1. Use a positive duration like --health-interval=30s.
2. Use 0 (or omit the flag) to accept the daemon default interval.
3. Check shell variable expansion is not prepending a stray minus sign.

Example fix

// before
docker run --health-interval=-5s --health-cmd=/check.sh myimage
// after
docker run --health-interval=5s --health-cmd=/check.sh myimage

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

When it happens

Trigger: Running `docker run --health-interval=-5s ...` or any value that parses to a negative time.Duration, while at least one health setting is present. A leading minus sign on the duration triggers it.

Common situations: A leading `-` typo when editing scripts; variable expansion producing `-<value>`; misunderstanding that 0 means default and trying to pass a negative to mean "faster".

Related errors

• --health-timeout cannot be negative
• --health-start-period cannot be negative
• --health-start-interval cannot be negative
• --health-retries cannot be negative
• --no-healthcheck conflicts with --health-* options

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

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