docker/compose · error

--build and --no-build are incompatible

Error message

--build and --no-build are incompatible

What it means

`docker compose create` rejects the simultaneous use of `--build` (force-build images before creating containers) and `--no-build` (never build). The PreRunE guard fails fast because the two flags encode contradictory build policies.

Source

Thrown at cmd/compose/create.go:66

	timeChanged   bool
	timeout       int
	quietPull     bool
	scale         []string
	AssumeYes     bool
}

func createCommand(p *ProjectOptions, dockerCli command.Cli, backendOptions *BackendOptions) *cobra.Command {
	opts := createOptions{}
	buildOpts := buildOptions{
		ProjectOptions: p,
	}
	cmd := &cobra.Command{
		Use:   "create [OPTIONS] [SERVICE...]",
		Short: "Creates containers for a service",
		PreRunE: AdaptCmd(func(ctx context.Context, cmd *cobra.Command, args []string) error {
			opts.pullChanged = cmd.Flags().Changed("pull")
			if opts.Build && opts.noBuild {
				return fmt.Errorf("--build and --no-build are incompatible")
			}
			if opts.forceRecreate && opts.noRecreate {
				return fmt.Errorf("--force-recreate and --no-recreate are incompatible")
			}
			return nil
		}),
		RunE: p.WithServices(dockerCli, func(ctx context.Context, project *types.Project, services []string) error {
			return runCreate(ctx, dockerCli, backendOptions, opts, buildOpts, project, services)
		}),
		ValidArgsFunction: completeServiceNames(dockerCli, p),
	}
	flags := cmd.Flags()
	flags.BoolVar(&opts.Build, "build", false, "Build images before starting containers")
	flags.BoolVar(&opts.noBuild, "no-build", false, "Don't build an image, even if it's policy")
	flags.StringVar(&opts.Pull, "pull", "policy", `Pull image before running ("always"|"missing"|"never"|"build")`)
	flags.BoolVar(&opts.quietPull, "quiet-pull", false, "Pull without printing progress information")
	flags.BoolVar(&opts.forceRecreate, "force-recreate", false, "Recreate containers even if their configuration and image haven't changed")
	flags.BoolVar(&opts.noRecreate, "no-recreate", false, "If containers already exist, don't recreate them. Incompatible with --force-recreate.")

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Remove one of the two flags — decide whether images should be built or not for this invocation.
2. If flags come from script variables, gate them: only pass `--build` when build is enabled, only pass `--no-build` when it is disabled.
3. Check `alias docker-compose` / function wrappers for hardcoded flags.

Example fix

# before
docker compose create --build --no-build

# after
# pick one policy:
docker compose create --build   # or: docker compose create --no-build

# bash: mutually exclusive build policy
BUILD_ARGS=()
if [ "$WANT_BUILD" = true ]; then BUILD_ARGS+=(--build); elif [ "$WANT_BUILD" = false ]; then BUILD_ARGS+=(--no-build); fi
docker compose create "${BUILD_ARGS[@]}"

When it happens

Trigger: Running `docker compose create --build --no-build` (directly or via a wrapper/alias that always adds one of the flags while the user types the other).

Common situations: Shell aliases or CI templates that hardcode `--no-build` for speed, then a developer adds `--build` to refresh an image; scripts forwarding both flags from independent toggles without mutual exclusion logic.

Related errors

• --force-recreate and --no-recreate are incompatible
• can't use --progress plain while ANSI support is forced
• invalid --pull option %q
• --service-ports and --publish are incompatible
• --tty and --no-tty can't be used together

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