docker/compose · error

--build and --no-build are incompatible

Error message

--build and --no-build are incompatible

What it means

Returned by validateFlags for `docker compose up` when both --build and --no-build are passed. --build forces building images before starting; --no-build forbids building even if policy suggests it. They are direct negations, so validateFlags rejects the combination before any work starts.

Source

Thrown at cmd/compose/up.go:207

//nolint:gocyclo
func validateFlags(up *upOptions, create *createOptions) error {
	if up.waitTimeout < 0 {
		return fmt.Errorf("--wait-timeout must be a non-negative integer")
	}
	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 {

View on GitHub (pinned to ddc4b044b6)

Solutions

  1. Remove one flag — decide whether this run builds (`--build`) or reuses existing images (`--no-build`, or just omit both to follow pull policy).
  2. Fix flag-assembly logic in scripts so the two toggles are mutually exclusive (if/else, not independent appends).

Example fix

# before
docker compose up --build --no-build

# after
docker compose up --build   # or: docker compose up --no-build
Defensive patterns

Strategy: validation

Validate before calling

if [[ "$UP_FLAGS" == *--build* && "$UP_FLAGS" == *--no-build* ]]; then
  echo 'choose --build or --no-build, not both' >&2; exit 2
fi

Prevention

When it happens

Trigger: `docker compose up --build --no-build`; wrapper scripts that append both flags from independent toggles (e.g. ALWAYS_BUILD and SKIP_BUILD env-derived flags concatenated into one command).

Common situations: Makefile/CI matrix where a 'fast path' adds --no-build and a 'rebuild path' adds --build and both end up enabled; aliases or shell history editing leaving a stale flag in place.

Related errors

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