docker/cli · error

--health-start-period cannot be negative

Error message

--health-start-period cannot be negative

What it means

Returned when --health-start-period is set to a negative duration (opts.go:587-589). Registered via flags.DurationVar with a version annotation of 1.29 (opts.go:267-268). The start period gives a container grace time before retries count; a negative value is invalid and rejected within the haveHealthSettings branch.

Solutions

1. Use a positive duration like --health-start-period=15s.
2. Use 0 (or omit) for no explicit start period.
3. Validate template arithmetic feeding this flag.

Example fix

// before
docker run --health-start-period=-10s --health-cmd=/check.sh myimage
// after
docker run --health-start-period=10s --health-cmd=/check.sh myimage

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

When it happens

Trigger: Running `docker run --health-start-period=-10s ...` or any negative duration while health settings are present. A parsed negative time.Duration triggers the guard.

Common situations: Typo'd minus sign; CI variable producing a negative; expecting 0 vs negative to mean different things (both effectively mean no grace period, but negative is rejected).

Related errors

• --health-start-interval 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/3a4421f307d70dac. Report an issue: GitHub.

Appendix: source

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

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

	deviceRequests := copts.gpus.Value()
	if len(cdiDeviceNames) > 0 {
		cdiDeviceRequest := container.DeviceRequest{

View on GitHub (pinned to 4f84911bfe)