[BUG] Confusing error messages when Bake mode requires BuildKit but it's not enabled

[error9098x]

Description

Docker Compose v2.17+ automatically switches to Bake mode when multiple build contexts are detected, but provides unclear error messages when BuildKit is not enabled, leading to confusing debugging sessions.

Steps to Reproduce

1. Create a docker-compose.yml with multiple services that have build: directives (5 in my case)
2. Ensure DOCKER_BUILDKIT is not set in the environment
3. Run docker compose up

Expected Behavior

One of the following:

1. Clear error message stating BuildKit is required:

ERROR: This build requires Docker BuildKit to be enabled.
Docker Compose detected multiple build contexts and will use Bake mode for parallel builds.

To enable BuildKit:
  export DOCKER_BUILDKIT=1
  export COMPOSE_DOCKER_CLI_BUILD=1

To use legacy builder instead:
  DOCKER_BUILDKIT=0 docker compose up

2. Or a configuration option to explicitly opt-in to Bake mode in the compose file itself

3. Or at minimum, don't silently assume BuildKit is available

Actual Behavior

Error messages are cryptic and don't mention BuildKit at all:

[+] Building 0.0s (1/1) FINISHED
 => [internal] load local bake definitions
 => => reading from stdin 2.72kB
unable to prepare context: path "/path/to/context" not found

Only when running with DOCKER_BUILDKIT=0 do you get:

time="..." level=warning msg="Docker Compose is configured to build using Bake, but buildkit isn't enabled"

This warning should appear BEFORE attempting the build, not buried in verbose output.

Environment

• Docker Compose version: v2.40.2-desktop.1
• Docker version: 28.5.1
• OS: macOS (Darwin)
• Compose file has 5 services with build contexts

Root Cause Analysis

Docker Compose v2.17+ introduced automatic Bake mode detection as an optimization. While this is good for performance, it breaks the principle of least surprise:

• No explicit configuration required or available in the YAML
• Assumes BuildKit is available on all systems
• Error messages don't explain what's actually required
• No migration guide for users upgrading from v2.16 or earlier

Proposed Solutions

Option 1: Fail fast with a clear message

• Detect Bake requirement during config parse
• Print helpful error before attempting build
• Suggest both enable BuildKit OR disable Bake

Option 2: Add explicit configuration

# docker-compose.yml
x-bake:
  enabled: true  # explicit opt-in

Option 3: Add a one-time setup check

NOTICE: Docker Compose detected multiple build contexts.
Bake mode (parallel builds) requires BuildKit.

Enable BuildKit now? [Y/n]

Additional Context

This has wasted significant debugging time. The path-based error message is a red herring - the path exists, but the build system can't access it properly without BuildKit. Users naturally debug the wrong problem (file permissions, symlinks, .dockerignore) instead of the actual problem (missing BuildKit).

The implicit behavior change between v2.16 and v2.17+ should have been more clearly communicated, ideally with a migration path that doesn't silently fail on older configurations.