docker/cli · error

-- conflicts with --health-* options

Error message

--%s conflicts with --health-* options

What it means

Raised by docker service update when --no-healthcheck is combined with any --health-* flag (--health-cmd, --health-interval, --health-retries, --health-timeout, or --health-start-period). These options are mutually exclusive because --no-healthcheck disables the healthcheck entirely while the --health-* options configure one, so the resulting intent is contradictory.

Solutions

1. Remove either --no-healthcheck or all --health-* flags so only one intent is expressed.
2. If you want to disable, keep only --no-healthcheck and drop --health-cmd/--health-interval/--health-retries/--health-timeout/--health-start-period.
3. If you want to reconfigure, drop --no-healthcheck and set the desired --health-* values.
4. Audit your automation/template that generates the update command to mutually exclude the two flag groups.

Example fix

// before
docker service update --no-healthcheck --health-cmd /bin/true myservice
// after
docker service update --no-healthcheck myservice

// Validate before building the update flag set
func hasHealthConfigFlag(flags []string) bool {
    set := map[string]struct{}{}
    for _, f := range flags {
        set[f] = struct{}{}
    }
    health := []string{"--health-cmd", "--health-interval", "--health-retries", "--health-timeout", "--health-start-period"}
    _, noHealth := set["--no-healthcheck"]
    if !noHealth {
        return false
    }
    for _, h := range health {
        if _, ok := set[h]; ok {
            return true // conflict
        }
    }
    return false
}

When it happens

Trigger: Calling `docker service update --no-healthcheck --health-cmd /bin/true <service>` (or any combination where both flagNoHealthcheck and at least one health-cmd/interval/retries/timeout/start-period flag are changed in the same invocation). The check at update.go:1270 fires inside updateHealthcheck when noHealthcheck is true and anyChanged(...) returns true for the health config flags.

Common situations: Copying a service update command from a runbook and leaving a stale --health-cmd while adding --no-healthcheck; scripting service updates with a flag matrix that doesn't exclude the two groups; migrating from a Dockerfile HEALTHCHECK to disabling it on the CLI while the old health flags are still templated in.

Related errors

• service is already attached to network
• node ID not found in /info
• when using secret driver secret data must be empty
• error reading from STDIN: data is empty
• secret file is required

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

Appendix: source

Thrown at cli/command/service/update.go:1276

func updateHealthcheck(flags *pflag.FlagSet, containerSpec *swarm.ContainerSpec) error {
	if !anyChanged(flags, flagNoHealthcheck, flagHealthCmd, flagHealthInterval, flagHealthRetries, flagHealthTimeout, flagHealthStartPeriod) {
		return nil
	}
	if containerSpec.Healthcheck == nil {
		containerSpec.Healthcheck = &container.HealthConfig{}
	}
	noHealthcheck, err := flags.GetBool(flagNoHealthcheck)
	if err != nil {
		return err
	}
	if noHealthcheck {
		if !anyChanged(flags, flagHealthCmd, flagHealthInterval, flagHealthRetries, flagHealthTimeout, flagHealthStartPeriod) {
			containerSpec.Healthcheck = &container.HealthConfig{
				Test: []string{"NONE"},
			}
			return nil
		}
		return fmt.Errorf("--%s conflicts with --health-* options", flagNoHealthcheck)
	}
	if len(containerSpec.Healthcheck.Test) > 0 && containerSpec.Healthcheck.Test[0] == "NONE" {
		containerSpec.Healthcheck.Test = nil
	}
	if flags.Changed(flagHealthInterval) {
		val := *flags.Lookup(flagHealthInterval).Value.(*opts.PositiveDurationOpt).Value()
		containerSpec.Healthcheck.Interval = val
	}
	if flags.Changed(flagHealthTimeout) {
		val := *flags.Lookup(flagHealthTimeout).Value.(*opts.PositiveDurationOpt).Value()
		containerSpec.Healthcheck.Timeout = val
	}
	if flags.Changed(flagHealthStartPeriod) {
		val := *flags.Lookup(flagHealthStartPeriod).Value.(*opts.PositiveDurationOpt).Value()
		containerSpec.Healthcheck.StartPeriod = val
	}
	if flags.Changed(flagHealthRetries) {
		containerSpec.Healthcheck.Retries, _ = flags.GetInt(flagHealthRetries)

View on GitHub (pinned to 4f84911bfe)