Failure diagnostics are poor when trying to use an image platform that is not supported by the builder

[piotrblasiak]

This is my pom:

<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration
					<image>
						<name>XXXX.amazonaws.com/${project.artifactId}:${project.version}</name>
						<imagePlatform>linux/arm64</imagePlatform>
						<builder>paketobuildpacks/builder-jammy-full</builder><!-- Include diagnostic tools for debugging -->
					</image>
				</configuration>
			</plugin>

And it fails:

[INFO] --- spring-boot:3.4.2:build-image (default-cli) @ backend ---
[INFO] Building image 'XXXXX.dkr.ecr.eu-west-1.amazonaws.com/backend:2302'
[INFO] 
[INFO]  > Pulling builder image 'docker.io/paketobuildpacks/builder-jammy-full:latest' for platform 'linux/arm64' 100%
[INFO]  > Pulled builder image 'paketobuildpacks/builder-jammy-full@sha256:5b3738739e97d37edb961773bf8d2c882914fa0e1e98c7f85b474d6a89a328b5'
[INFO]  > Pulling run image 'docker.io/paketobuildpacks/run-jammy-full:latest' for platform 'linux/arm64' 100%
[INFO]  > Pulled run image 'paketobuildpacks/run-jammy-full@sha256:03cbe69ed0752182c8035e992e1eaa166f1227ef3bc0627dc196295c84d4d7ef'
[INFO]  > Executing lifecycle version v0.20.5
[INFO]  > Using build cache volume 'pack-cache-5b8cfaffe55b.build'
[INFO] 
[INFO]  > Running creator
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  14.091 s
[INFO] Finished at: 2025-02-04T09:48:13+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.springframework.boot:spring-boot-maven-plugin:3.4.2:build-image (default-cli) on project backend: Execution default-cli of goal org.springframework.boot:spring-boot-maven-plugin:3.4.2:build-image failed: Docker API call to '/Users/piotr/.docker/run/docker.sock/v1.41/containers/create?platform=linux%2Farm64' failed with status code 404 "Not Found" -> [Help 1]

[wilkinsona]

paketobuildpacks/builder-jammy-full is not a multi-arch image. Somewhat unhelpfully, when Docker's asked to pull a particular platform for a non-multi-arch image it falls back to the single-arch image that may then not have a matching OS and architecture. It's this mismatch that is causing the 404 when using platform on container creation:

When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a 404 status.

The default builder, paketobuildpacks/builder-jammy-java-tiny, is a multi-arch image. It should work if you use this builder but you'll lose the debugging tools that builder-jammy-full contains. I'll check with the Buildpacks team on the state of play with base and full builders that are multi-arch but this is out of Boot's control.

In Boot, we may at least be able to catch the mismatch when we try to pull a multi-arch image and receive a non-matching single-arch image instead. If so, we could fail fast with a more helpful error message.

[dashaun]

@piotrblasiak which buildpack do you need from builder-jammy-full?

[piotrblasiak]

Ok, thanks for letting me know. @dashaun I need it for the debugging tools.

[wilkinsona]

From the buildpack team:

builder-jammy-full not only comes with a stack with more tools, but also with support for many other programming languages; most of them not ready for dual arch, hence we never dual stack'ed it, and given Jammy age, probably that won't happen.

We'll look at improving the diagnostics in Boot by detecting the fallback to the single-arch image that doesn't match the requested platform and failing fast.

Noble though, in the Paketo community, was decided to be dual arch only, so all Noble builder (when they're out) should be dual arch.

You may want to track the Noble builders and consider using them in the future. #42711 is tracking Boot switching to Noble by default.

[mhalbritter]

The problem is in org.springframework.boot.buildpack.platform.docker.transport.HttpClientTransport#execute(org.apache.hc.client5.http.classic.methods.HttpUriRequest):

There we do this:

if (statusCode >= 400 && statusCode <= 500) {
	HttpEntity entity = response.getEntity();
	Errors errors = (statusCode != 500) ? getErrorsFromResponse(entity) : null;
	Message message = getMessageFromResponse(entity);
}

as the status code is 404, we try to read the errors from the response. This consumes the http entity. When we call getMessageFromResponse the http entity is already consumed, and this returns null. Which is bad in this case, as the error message would be quite helpful here. I'm going to change this to read the content in a byte[] and then deserialize the errors and the message from that. This should fix this issue and generally improve the diagnostics if Docker API call failures happen.

[wilkinsona]

IIRC, when I was looking at this a few weeks ago, I thought it should be possible to detect the problem before we receive the 404. When the request for the multi-arch image is satisfied with a single-arch image, we should be able to check the image and fail at that point. That's before we make the request that results in a 404.

[mhalbritter]

Okay, I'll double check. I'll open a new issue for always including the message.

[mhalbritter]

We now check that the platform of the image is the same as the requested platform. If not, we fail with an exception with a useful error message:

Image platform mismatch detected. The configured platform 'invalid/platform' is not supported by the image 'ghcr.io/spring-io/spring-boot-cnb-test-builder:0.0.1'. Requested platform 'invalid/platform' but got 'linux/amd64'.