docker/cli · error

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

Error message

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

What it means

Returned when --no-healthcheck is combined with any non-zero --health-* option (opts.go:562-571). haveHealthSettings is true if any of healthCmd, healthInterval, healthTimeout, healthStartPeriod, healthRetries, or healthStartInterval is set. --no-healthcheck writes Test=["NONE"] which semantically contradicts defining a probe, so the conflict is rejected at parse time.

Solutions

1. Remove --no-healthcheck if you want to define a custom probe via --health-*.
2. Remove all --health-* flags if you want to disable the image's HEALTHCHECK via --no-healthcheck.
3. Audit compose files / CI templates for both blocks being emitted together.

Example fix

// before
docker run --no-healthcheck --health-cmd=/check.sh myimage
// after
docker run --health-cmd=/check.sh myimage

// Reject the --no-healthcheck + any --health-* combination up front.
if copts.noHealthcheck {
    if copts.healthCmd != "" || copts.healthInterval != 0 || copts.healthTimeout != 0 ||
        copts.healthRetries != 0 || copts.healthStartPeriod != 0 || copts.healthStartInterval != 0 {
        return errors.New("--no-healthcheck conflicts with --health-* options")
    }
}

When it happens

Trigger: Running `docker run --no-healthcheck --health-cmd=... ...` or pairing --no-healthcheck with any --health-interval/--health-timeout/--health-retries/--health-start-period/--health-start-interval. Triggered when haveHealthSettings is true alongside copts.noHealthcheck.

Common situations: Copy-pasting a base image's HEALTHCHECK-disabling flags while also layering new health options; overriding an image HEALTHCHECK by passing both --no-healthcheck and a new --health-cmd by mistake; templating tools (compose, helm) emitting both blocks.

Related errors

• --health-interval cannot be negative
• --health-timeout cannot be negative
• --health-retries cannot be negative
• --health-start-period cannot be negative
• --health-start-interval cannot be negative

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

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