docker/compose · error

cannot combine %s and --remove-orphans

Error message

cannot combine %s and --remove-orphans

What it means

Returned by the `up` command's RunE when both orphan removal and explicit orphan ignoring are active. create.removeOrphans is set by the --remove-orphans flag (or the COMPOSE_REMOVE_ORPHANS env var when the flag is not passed), while create.ignoreOrphans comes from the project-level COMPOSE_IGNORE_ORPHANS environment variable. The two options are contradictory — remove vs. keep containers for services no longer in the file — so Compose refuses to run.

Source

Thrown at cmd/compose/up.go:132

	up := upOptions{}
	create := createOptions{}
	build := buildOptions{ProjectOptions: p}
	upCmd := &cobra.Command{
		Use:   "up [OPTIONS] [SERVICE...]",
		Short: "Create and start containers",
		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
			create.pullChanged = cmd.Flags().Changed("pull")
			create.timeChanged = cmd.Flags().Changed("timeout")
			up.navigationMenuChanged = cmd.Flags().Changed("menu")
			if !cmd.Flags().Changed("remove-orphans") {
				create.removeOrphans = utils.StringToBool(os.Getenv(ComposeRemoveOrphans))
			}
			return validateFlags(&up, &create)
		}),
		RunE: p.WithServices(dockerCli, func(ctx context.Context, project *types.Project, services []string) error {
			create.ignoreOrphans = utils.StringToBool(project.Environment[ComposeIgnoreOrphans])
			if create.ignoreOrphans && create.removeOrphans {
				return fmt.Errorf("cannot combine %s and --remove-orphans", ComposeIgnoreOrphans)
			}
			if len(up.attach) != 0 && up.attachDependencies {
				return errors.New("cannot combine --attach and --attach-dependencies")
			}

			up.resolveNavigationMenu(dockerCli)

			if !p.All && len(project.Services) == 0 {
				return fmt.Errorf("no service selected")
			}

			return runUp(ctx, dockerCli, backendOptions, create, up, build, project, services)
		}),
		ValidArgsFunction: completeServiceNames(dockerCli, p),
	}
	flags := upCmd.Flags()
	flags.BoolVarP(&up.Detach, "detach", "d", false, "Detached mode: Run containers in the background")
	flags.BoolVar(&create.Build, "build", false, "Build images before starting containers")

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Drop one of the two: either unset COMPOSE_IGNORE_ORPHANS for the project (`unset COMPOSE_IGNORE_ORPHANS` or remove it from .env/compose.yml environment) or omit --remove-orphans.
2. If you need removal, run with the variable explicitly disabled: `COMPOSE_IGNORE_ORPHANS=false docker compose up --remove-orphans` (the flag takes precedence when passed).
3. Audit .env files and exported variables in CI for COMPOSE_IGNORE_ORPHANS before adding --remove-orphans to scripts.

Example fix

# before
# .env contains COMPOSE_IGNORE_ORPHANS=true
docker compose up --remove-orphans

# after
# remove COMPOSE_IGNORE_ORPHANS from .env (or override it)
COMPOSE_IGNORE_ORPHANS=false docker compose up --remove-orphans

# in the wrapper, resolve the conflict before up
if [ "${COMPOSE_IGNORE_ORPHANS:-}" = true ] && [[ "$*" == *--remove-orphans* ]]; then
  unset COMPOSE_IGNORE_ORPHANS
fi
docker compose up "$@"

When it happens

Trigger: Project environment (or .env) sets COMPOSE_IGNORE_ORPHANS=true and the user also runs `docker compose up --remove-orphans`; or COMPOSE_REMOVE_ORPHANS=true in the environment and COMPOSE_IGNORE_ORPHANS=true in the project env. The check runs inside p.WithServices after project env resolution, so any combination resolving both to true trips it.

Common situations: CI pipelines that export COMPOSE_REMOVE_ORPHANS=true globally while a compose.yml (or exported project env) sets COMPOSE_IGNORE_ORPHANS to silence orphan warnings locally; teams sharing a .env with the variable set; renaming services and trying --remove-orphans to clean up while the ignore variable leaks from a wrapper script.

Related errors

• --wait-timeout must be a non-negative integer
• --abort-on-container-failure cannot be combined with --abort
• --wait cannot be combined with --abort-on-container-exit, --
• --build and --no-build are incompatible
• --wait cannot be combined with --abort-on-container-exit, --

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