docker/cli · error

--no-healthcheck conflicts with --health-* options

Error message

--no-healthcheck conflicts with --health-* options

What it means

When --no-healthcheck is set, the CLI checks whether any health-related flag (--health-cmd, --health-interval, --health-timeout, --health-start-period, --health-retries, --health-start-interval) was also given (opts.go:562-571). Since --no-healthcheck writes a HealthConfig of Test=["NONE"] that disables checks entirely, combining it with health tuning flags is contradictory and rejected.

Source

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

	securityOpts, maskedPaths, readonlyPaths := parseSystemPaths(securityOpts)

	storageOpts, err := parseStorageOpts(copts.storageOpt.GetSlice())
	if err != nil {
		return nil, err
	}

	// Healthcheck
	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")

View on GitHub (pinned to e9452d6e78)

Solutions

1. Remove the --health-* flags if you intend to disable the healthcheck with --no-healthcheck
2. Remove --no-healthcheck if you intend to override the image's healthcheck with custom --health-* settings
3. In templating, make the two option groups mutually exclusive branches

Example fix

# before
docker run --no-healthcheck --health-interval=30s myimage
# after (disable entirely)
docker run --no-healthcheck myimage
# or (customize instead)
docker run --health-interval=30s myimage

When it happens

Trigger: `docker run --no-healthcheck --health-cmd 'curl -f localhost' ...` or any combination of --no-healthcheck with a non-zero/non-empty --health-* flag on run/create. Note haveHealthSettings triggers on any non-zero value, so even --health-retries=1 alongside --no-healthcheck errors.

Common situations: Templated CI/compose-to-run conversions that emit both flags conditionally; adding --no-healthcheck to silence a noisy image healthcheck while leaving old --health-* overrides in the script; wrapper scripts that always append default health flags.

Related errors

• conflicting options: cannot attach both user-defined and non
• --userns: invalid USER mode
• --cgroupns: invalid CGROUP mode
• --health-interval cannot be negative
• --health-timeout cannot be negative

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/3ccd24350d0832ce.json. Report an issue: GitHub.