[Enhancement/Bug*]: Testcontainers does not fall back to linux/amd64 when registry returns missing architecture

[MichaelLykkeStrand]

Module

Core

Testcontainers version

1.21.4

Using the latest Testcontainers version?

Yes

Host OS

Mac

Host Arch

arm64

Docker version

podman version
Client:        Podman Engine
Version:       5.6.2
API Version:   5.6.2
Go Version:    go1.25.1
Git Commit:    9dd5e1ed33830612bc200d7a13db00af6ab865a4
Built:         Tue Sep 30 21:35:47 2025
Build Origin:  pkginstaller
OS/Arch:       darwin/arm64

Server:       Podman Engine
Version:      5.6.2
API Version:  5.6.2
Go Version:   go1.24.7
Git Commit:   9dd5e1ed33830612bc200d7a13db00af6ab865a4
Built:        Tue Sep 30 02:00:00 2025
OS/Arch:      linux/arm64

What happened?

Expected behavior
When pulling a Docker image that only provides a linux/amd64 platform, Testcontainers should automatically fall back to linux/amd64 on ARM-based hosts (e.g. Apple Silicon Macs), as it already does for DockerClientException and NotFoundException.

Actual behavior
Registries like JFrog Artifactory may return:
com.github.dockerjava.api.exception.InternalServerErrorException: Status 500: {"message":"no image found in manifest list for architecture \"arm64\", variant \"v8\", OS \"linux\""}

While the 500 Internal server error from JFrog is arguably misleading/incorrect I still think testcontainers should provide an option to specify the arch or fallback strategy outside of using a direct image SHA.

Relevant log output

com.github.dockerjava.api.exception.InternalServerErrorException: Status 500: {"message":"no image found in manifest list for architecture \"arm64\", variant \"v8\", OS \"linux\""}

	at org.testcontainers.shaded.com.github.dockerjava.core.DefaultInvocationBuilder.execute(DefaultInvocationBuilder.java:247)
	at org.testcontainers.shaded.com.github.dockerjava.core.DefaultInvocationBuilder.lambda$executeAndStream$1(DefaultInvocationBuilder.java:269)
	at java.base/java.lang.Thread.run(Thread.java:1474)

2026-05-27T12:16:09.667+02:00  WARN 46613 --- [    Test worker] [] t.r.b.d.4.0.11-r2                        : Retrying pull for image: registry.bankdata.dev/all-docker-centrals/ibm-messaging/mq:9.4.0.11-r2 (112s remaining)
2026-05-27T12:16:13.150+02:00 ERROR 46613 --- [ream--322867326] [] c.g.d.api.async.ResultCallbackTemplate   : Error during callback

com.github.dockerjava.api.exception.InternalServerErrorException: Status 500: {"message":"no image found in manifest list for architecture \"arm64\", variant \"v8\", OS \"linux\""}

Additional Information

Issue has great similarity to:
issues/9214:pull/9200
but I am unsure if it qualifies as a bug or an enhancement.

Would love to get some input. Won't fix is a very valid response as the issue is primarily JFrog related.

[anushkasrvstv]

/assign

[Jaiswal-Devpriya]

Hi @MichaelLykkeStrand,
I investigated this issue and opened a PR with a proposed fix:

#11841

The change extends the existing linux/amd64 fallback path to also handle InternalServerErrorException responses that can occur when registries report a missing ARM64 manifest.