bootBuildImage failure due to fixed Docker API versions in ImageApi.pull()

[hiro345g]

Description

The bootBuildImage Gradle task fails because the pull() method in org.springframework.boot.buildpack.platform.docker.ImageApi.java uses hardcoded values (PLATFORM_API_VERSION or API_VERSION) to specify the Docker API version when building the request URI for image creation (pulling).

Since the fixed API versions are older than the minimum required by the latest Docker Engine versions, the API call fails with an HTTP 400 "Bad Request" error, preventing the image from being pulled and the build from completing.

Root Cause in ImageApi.java

In the pull() method, buildUrl() uses fixed API versions:

// ...
      URI createUri = (platform != null)
          ? buildUrl(PLATFORM_API_VERSION, "/images/create", "fromImage", reference, "platform", platform)
          : buildUrl("/images/create", "fromImage", reference);
// ...
        return inspect((platform != null) ? PLATFORM_API_VERSION : API_VERSION, reference);
// ...

• When platform is not specified, the request is made with the fixed API_VERSION (which appears to be v1.24).
• When platform is specified (e.g., in build.gradle), the request is made with the fixed PLATFORM_API_VERSION (which appears to be v1.41).

Neither of these fixed versions meets the minimum API version (1.44) required by modern Docker Engine installations.

Steps to Reproduce

1. Project Setup: Create a standard Spring Boot project using the provided command:

   spring init \
     --type=gradle-project-kotlin \
     --language=java \
     --bootVersion=3.5.7 \
     --name=spring-bellsoft \
     --groupId=internal.dev \
     --artifactId=spring-bellsoft \
     --packageName=internal.dev.spring_bellsoft \
     --dependencies=web \
     --javaVersion=17 \
     spring-bellsoft

2. Execute Task (Without imagePlatform): Run the bootBuildImage task.

   ./gradlew bootBuildImage

   • Expected Behavior: Image build succeeds using the Docker Engine's actual minimum supported API version (1.44 or higher).
   • Observed Behavior (Failure 1 - API v1.24): The build fails because the request uses an outdated API version (v1.24).
3. Execute Task (With imagePlatform): Modify build.gradle.kts to specify a platform:

   import org.springframework.boot.gradle.tasks.bundling.BootBuildImage // Added line
   (snip)
   tasks.named<BootBuildImage>("bootBuildImage") {  imagePlatform = "linux/amd64" } // Added line

   Then, run the task again:

   ./gradlew bootBuildImage

   • Observed Behavior (Failure 2 - API v1.41): The build fails because the request now uses a different outdated API version (v1.41).

Failure Details & Logs

Failure without imagePlatform (API v1.24)

The bootBuildImage output shows the request using /v1.24/:

> Task :bootBuildImage FAILED
...
* What went wrong:
Execution failed for task ':bootBuildImage'.
> Docker API call to '.../v1.24/images/create?fromImage=docker.io%2Fpaketobuildpacks%2Fbuilder-noble-java-tiny%3Alatest' failed with status code 400 "Bad Request" and message "client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"

The dockerd log confirms the rejected request:

Nov 11 18:25:40 ... dockerd[43806]: time="2025-11-11T18:25:40.540416180+09:00" level=debug msg="error response for POST request" error-response="client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" method=POST module=api request-url="/v1.24/images/create?fromImage=docker.io%2Fpaketobuildpacks%2Fbuilder-noble-java-tiny%3Alatest" status=400 vars="map[version:1.24]"

Failure with imagePlatform = "linux/amd64" (API v1.41)

The bootBuildImage output shows the request using /v1.41/:

> Docker API call to '.../v1.41/images/create?fromImage=docker.io%2Fpaketobuildpacks%2Fbuilder-noble-java-tiny%3Alatest&platform=linux%2Famd64' failed with status code 400 "Bad Request" and message "client version 1.41 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"

The dockerd log confirms the rejected request:

Nov 11 18:24:27 ... dockerd[43806]: time="2025-11-11T18:24:27.597508445+09:00" level=debug msg="error response for POST request" error-response="client version 1.41 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" method=POST module=api request-url="/v1.41/images/create?fromImage=docker.io%2Fpaketobuildpacks%2Fbuilder-noble-java-tiny%3Alatest&platform=linux%2Famd64" status=400 vars="map[version:1.41]"

Environment

Used Docker Engine Version

The installed Docker Engine requires a minimum API version of 1.44.

$ docker version
Client: Docker Engine - Community
 Version:           29.0.0
 API version:       1.52
...
Server: Docker Engine - Community
 Engine:
  Version:          29.0.0
  API version:      1.52 (minimum version 1.44)
...

curl Success Example (Using correct v1.52)

Manually using the correct API version works as expected:

$ curl -X POST --unix-socket /var/run/docker.sock \
  "http://localhost/v1.52/images/create?fromImage=docker.io%2Fpaketobuildpacks%2Fbuilder-noble-java-tiny%3Alatest"
{"status":"Pulling from paketobuildpacks/builder-noble-java-tiny","id":"latest"}
...
{"status":"Status: Image is up to date for paketobuildpacks/builder-noble-java-tiny:latest"}

Suggested Fix

The bootBuildImage utility should either:

1. Dynamically determine the highest supported Docker API version using the /version endpoint and use it for requests, or
2. Use the minimum supported API version (MinAPIVersion from /version endpoint, which is 1.44 in this case) to ensure compatibility with modern Docker Engine versions.

[wilkinsona]

Thanks for the report. This is due to a breaking change in 29.0:

The daemon now requires API version v1.44 or later (Docker v25.0+).

We'll see what we can do. In the meantime, any earlier version of Docker should continue to work.