docker/cli · error

--health-start-interval cannot be negative

Error message

--health-start-interval cannot be negative

What it means

Returned when --health-start-interval is set to a negative duration (opts.go:590-592). The flag is registered via flags.DurationVar with a version annotation of 1.44 (opts.go:269-270), the most recent addition to the healthcheck options. It controls the check interval during the start period; negative values are rejected within the haveHealthSettings branch.

Solutions

1. Use a positive duration like --health-start-interval=5s.
2. Use 0 (or omit) to inherit the daemon default.
3. Confirm the daemon supports API 1.44 (`docker version`).

Example fix

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

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

When it happens

Trigger: Running `docker run --health-start-interval=-2s ...` or any negative duration while health settings are present. Requires API version 1.44+ on the daemon.

Common situations: Typo'd minus sign; passing a negative because the start-period interval is new and semantics are unclear; daemon older than 1.44 that does not recognize the flag (pflag still parses it client-side, then the guard fires).

Related errors

• --health-start-period cannot be negative
• --health-interval cannot be negative
• --health-timeout cannot be negative
• --health-retries cannot be negative
• --cgroupns: invalid CGROUP mode

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

Appendix: source

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

	} 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,
		}
	}

	deviceRequests := copts.gpus.Value()
	if len(cdiDeviceNames) > 0 {
		cdiDeviceRequest := container.DeviceRequest{
			Driver:    "cdi",
			DeviceIDs: cdiDeviceNames,
		}

View on GitHub (pinned to 4f84911bfe)