[Bug]: After upgrading from 2.0.3 to 2.0.4, testcontainers fails to start, throwing ClassNotFoundException

[andrezimmermann]

Module

PostgreSQL

Testcontainers version

2.0.4

Using the latest Testcontainers version?

Yes

Host OS

MacOS

Host Arch

ARM

Docker version

Client:
 Version:           29.2.1
 API version:       1.53
 Go version:        go1.25.6
 Git commit:        a5c7197
 Built:             Mon Feb  2 17:16:37 2026
 OS/Arch:           darwin/arm64
 Context:           desktop-linux

Server: Docker Desktop 4.62.0 (219486)
 Engine:
  Version:          29.2.1
  API version:      1.53 (minimum version 1.44)
  Go version:       go1.25.6
  Git commit:       6bc6209
  Built:            Mon Feb  2 17:16:47 2026
  OS/Arch:          linux/arm64
  Experimental:     false
 containerd:
  Version:          v2.2.1
  GitCommit:        dea7da592f5d1d2b7755e3a161be07f43fad8f75
 runc:
  Version:          1.3.4
  GitCommit:        v1.3.4-0-gd6d73eb8
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

What happened?

Upgrading from 2.0.3 to 2.0.4 makes the testcontainers to fail to start

Relevant log output

2026-03-25 13:52:13,984 ERROR [org.testcontainers.dockerclient.DockerClientProviderStrategy] (testcontainers-lifecycle-0) Could not find a valid Docker environment. Please check configuration. Attempted configurations were:
	UnixSocketClientProviderStrategy: failed with exception NoClassDefFoundError (com/github/dockerjava/api/command/ImageHistoryCmd). Root cause ClassNotFoundException (com.github.dockerjava.api.command.ImageHistoryCmd)
	DockerDesktopClientProviderStrategy: failed with exception NoClassDefFoundError (com/github/dockerjava/api/command/ImageHistoryCmd). Root cause ClassNotFoundException (com.github.dockerjava.api.command.ImageHistoryCmd)As no valid configuration was found, execution cannot continue.
See https://java.testcontainers.org/on_failure.html for more details.

Additional Information

There is nothing special about my gradle project

Using the dependency catalog feature

testcontainers-bom = { module = "org.testcontainers:testcontainers-bom", version.ref = "2.0.4"}
testcontainers-postgresql = { module = "org.testcontainers:testcontainers-postgresql"}

Then I import as follows

    testFixturesImplementation(enforcedPlatform(libs.testcontainers.bom))
    testFixturesImplementation(libs.testcontainers.postgresql)

2.0.3 works without any issues, but 2.0.4 fails, this is not machine dependent as is reproducible in any machine

[mgorzcom]

Similar problem. It look's like problem with dependency management

I see that my problem is using testcontainers-bom and quarkus-bom

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-bom</artifactId>
    <version>2.0.4</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>
<dependency>
    <groupId>io.quarkus.platform</groupId>
    <artifactId>quarkus-bom</artifactId>
    <version>3.27.1</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

With the same quarkus version (3.27.1) proper docker-java-api version is used for testcontainers-bom 2.0.3.
Stop working for testcontainers-bom 2.0.4.
Overriding

<dependency>
    <groupId>com.github.docker-java</groupId>
    <artifactId>docker-java-api</artifactId>
    <version>3.7.1</version>
</dependency>

helps

[eddumelendez]

looks like version aligment on quarkus

[MatthewRyanRead]

I ran into this with docker-java 3.7.0 — thanks for filing this, it helped me figure it out. There ought to be a testcontainers-dependencies-bom that we could import to help avoid such conflicts.