docker/cli · error

--health-start-interval cannot be negative

Error message

--health-start-interval cannot be negative

What it means

--health-start-interval (added with API 1.44 / Docker 25) sets the probe interval used during the start period; the CLI rejects negative durations before sending the create request (opts.go:590-592). As with the other health durations, 0 means 'default' and negatives are meaningless.

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 e9452d6e78)

Solutions

1. Set a positive duration, e.g. --health-start-interval=2s
2. Omit the flag or pass 0 to fall back to the default behavior
3. Ensure the daemon supports API 1.44+ if you rely on this flag at all

Example fix

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

When it happens

Trigger: `docker run --health-cmd '...' --health-start-interval=-2s image` on run/create; any negative duration reaching this flag while other health settings are present.

Common situations: Negative values from script variables; trying sentinel semantics (-1) to disable the faster start-period probing; also note older daemons (<25.0/API 1.44) reject this flag entirely, a separate but related pitfall.

Related errors

• --health-interval cannot be negative
• --health-timeout cannot be negative
• --health-start-period 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/79b6e93003e10f63.json. Report an issue: GitHub.