--wait cannot be combined with --abort-on-container-exit, --

Error message

--wait cannot be combined with --abort-on-container-exit, --abort-on-container-failure, --attach, --attach-dependencies or --watch

What it means

Returned by validateFlags when detached mode is active (directly via --detach, or implicitly because --wait set up.Detach = true) AND one of the attach-family flags is set: --attach-dependencies, --abort-on-container-exit (cascadeStop), --abort-on-container-failure (cascadeFail), explicit --attach, or --watch. Attaching to output or cascading on container exit only makes sense in foreground mode, so the combination is rejected. The '--wait' variant of the message is used because --wait forced detach earlier in the same function.

Source

Thrown at cmd/compose/up.go:211

	}
	if up.exitCodeFrom != "" && !up.cascadeFail {
		up.cascadeStop = true
	}
	if up.cascadeStop && up.cascadeFail {
		return fmt.Errorf("--abort-on-container-failure cannot be combined with --abort-on-container-exit")
	}
	if up.wait {
		if up.attachDependencies || up.cascadeStop || len(up.attach) > 0 {
			return fmt.Errorf("--wait cannot be combined with --abort-on-container-exit, --attach or --attach-dependencies")
		}
		up.Detach = true
	}
	if create.Build && create.noBuild {
		return fmt.Errorf("--build and --no-build are incompatible")
	}
	if up.Detach && (up.attachDependencies || up.cascadeStop || up.cascadeFail || len(up.attach) > 0 || up.watch) {
		if up.wait {
			return fmt.Errorf("--wait cannot be combined with --abort-on-container-exit, --abort-on-container-failure, --attach, --attach-dependencies or --watch")
		} else {
			return fmt.Errorf("--detach cannot be combined with --abort-on-container-exit, --abort-on-container-failure, --attach, --attach-dependencies or --watch")
		}
	}
	if create.noInherit && create.noRecreate {
		return fmt.Errorf("--no-recreate and --renew-anon-volumes are incompatible")
	}
	if create.forceRecreate && create.noRecreate {
		return fmt.Errorf("--force-recreate and --no-recreate are incompatible")
	}
	if create.recreateDeps && create.noRecreate {
		return fmt.Errorf("--always-recreate-deps and --no-recreate are incompatible")
	}
	if create.noBuild && up.watch {
		return fmt.Errorf("--no-build and --watch are incompatible")
	}
	return nil
}

View on GitHub (pinned to ddc4b044b6)

Solutions

Split the behaviors: `docker compose up --wait` for readiness, then separately `docker compose watch` or `logs -f`.
Drop --wait if you need --watch/--attach/--abort flags and rely on their own semantics.
Use `up -d` plus `docker compose ps --wait`-style polling if you need detached + monitored behavior.

Example fix

# before
docker compose up --wait --watch

# after
docker compose up --wait
docker compose watch

Defensive patterns

Strategy: validation

Validate before calling

if [[ "$UP_FLAGS" == *--wait* ]]; then
  for f in --attach --attach-dependencies --abort-on-container-exit --abort-on-container-failure --watch; do
    [[ "$UP_FLAGS" == *"$f"* ]] && { echo "--wait conflicts with $f" >&2; exit 2; }
  done
fi

Prevention

Remember --wait implies detach; anything attach-like conflicts.
Run watch as its own `docker compose watch` command.
Prefer healthchecks + --wait over exit-based flow in CI.

When it happens

Trigger: `docker compose up --wait --watch`; `up --wait --abort-on-container-failure` (wait sets Detach, then the Detach branch with wait=true fires); note the earlier line 202 check usually catches simpler --wait+attach combos first, so this branch is reached for combos like --wait --watch or --wait --abort-on-container-failure.

Common situations: Wanting health-based wait plus watch mode for dev; CI passing --wait with abort flags copied from another job; scripts defaulting to --wait and layering --watch for iteration.

Related errors

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/6eca8304cfff3750. Report an issue: GitHub.