[Bug]: Docker 29.0.0 could not find a valid Docker environment

[simi1401]

Module

Core

Testcontainers version

2.0.1

Using the latest Testcontainers version?

Yes

Host OS

Linux

Host Arch

x86

Docker version

Client: Docker Engine - Community
 Version:           29.0.0
 API version:       1.52
 Go version:        go1.25.4
 Git commit:        3d4129b
 Built:             Mon Nov 10 21:46:24 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          29.0.0
  API version:      1.52 (minimum version 1.44)
  Go version:       go1.25.4
  Git commit:       d105562
  Built:            Mon Nov 10 21:46:24 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v2.1.5
  GitCommit:        fcd43222d6b07379a4be9786bda52438f0dd16a1
 runc:
  Version:          1.3.3
  GitCommit:        v1.3.3-0-gd842d771
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

What happened?

After updating Docker to version 29, the Docker environment could no longer be found.
After downgrading to version 28.5.2, it worked again.

According to Docker, there are breaking changes in this version.

Relevant log output

java.lang.RuntimeException: Could not start local database
	at base.database.LocalDatabaseExtension.beforeAll(LocalDatabaseExtension.java:78)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)
Caused by: java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configuration
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.lambda$getFirstValidStrategy$7(DockerClientProviderStrategy.java:274)
	at java.base/java.util.Optional.orElseThrow(Optional.java:403)
	at org.testcontainers.dockerclient.DockerClientProviderStrategy.getFirstValidStrategy(DockerClientProviderStrategy.java:265)
	at org.testcontainers.DockerClientFactory.getOrInitializeStrategy(DockerClientFactory.java:154)
	at org.testcontainers.DockerClientFactory.client(DockerClientFactory.java:196)
	at org.testcontainers.DockerClientFactory$1.getDockerClient(DockerClientFactory.java:108)
	at com.github.dockerjava.api.DockerClientDelegate.authConfig(DockerClientDelegate.java:109)
	at org.testcontainers.containers.GenericContainer.start(GenericContainer.java:316)
	at base.database.DockerMariaDB.startContainer(DockerMariaDB.java:32)
	at base.database.LocalDatabase.startDockerMariaDB(LocalDatabase.java:36)
	at base.database.LocalDatabase.start(LocalDatabase.java:28)
	at base.database.LocalDatabaseExtension.beforeAll(LocalDatabaseExtension.java:58)
	... 1 more

Additional Information

No response

[matzegebbe]

Looks like quite a big jump in the Docker API - from minimum version 1.24 to 1.44.

Our Testcontainers setup reports:

Client version 1.32 is too old. Minimum supported API version is 1.44. Please upgrade your client to a newer version.

podman run --rm --privileged -it docker:28-dind
# vs
podman run --rm --privileged -it docker:29-dind

docker:29-dind was released Nov 11, 2025 at 7:08 am (4h ago by writing this) https://hub.docker.com/_/docker/tags?name=-dind

[msstaicu]

There is this code that sets the TC version if it cannot find a declared one:

`public static DockerClient getClientForConfig(TransportConfig transportConfig) {
final DockerHttpClient dockerHttpClient;

    String transportType = TestcontainersConfiguration.getInstance().getTransportType();
    switch (transportType) {
        case "httpclient5":
            dockerHttpClient =
                new ZerodepDockerHttpClient.Builder()
                    .dockerHost(transportConfig.getDockerHost())
                    .sslConfig(transportConfig.getSslConfig())
                    .build();
            break;
        default:
            throw new IllegalArgumentException("Unknown transport type '" + transportType + "'");
    }

    DefaultDockerClientConfig.Builder configBuilder = DefaultDockerClientConfig.createDefaultConfigBuilder();

    if (configBuilder.build().getApiVersion() == RemoteApiVersion.UNKNOWN_VERSION) {
        configBuilder.withApiVersion(RemoteApiVersion.VERSION_1_32);
    }
    Map<String, String> headers = new HashMap<>();
    headers.put("x-tc-sid", DockerClientFactory.SESSION_ID);
    headers.put("User-Agent", String.format("tc-java/%s", DockerClientFactory.TESTCONTAINERS_VERSION));

    return DockerClientImpl.getInstance(
        new AuthDelegatingDockerClientConfig(
            configBuilder.withDockerHost(transportConfig.getDockerHost().toString()).build()
        ),
        new HeadersAddingDockerHttpClient(dockerHttpClient, headers)
    );
}

`

This is causing the test to run with an old client version. I don't know what was changed in the new docker release, actively looking in to this also.

[msstaicu]

Apparently docker is requiring now minimum 1.44 API version, so TC is not working anymore unless we override the api version via ENV variables or docker-java.properties in the project.

[tomas-forsman]

Workaround is to set the client version explicitly.
For instance in $HOME/.docker-java.properties

api.version=1.44

[leun4m]

relates to #11210

[KengoTODA]

First of all, thank you testcontainers contributors for your continuous contribution!

Today I have faced the same issue, and solved it by setting api.version system property.
Probably the root cause of this issue is here; testcontainers-java sets docker remote API version explicitly in case of no API version is set via configurations.

testcontainers-java/core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java

Lines 406 to 408 in 73726f4

	if (configBuilder.build().getApiVersion() == RemoteApiVersion.UNKNOWN_VERSION) {
	configBuilder.withApiVersion(RemoteApiVersion.VERSION_1_32);
	}

I guess that we can change these lines to use VERSION_1_44 by default, or simply remove these lines to let docker-java negotiates proper version with docker server. But I'm not so sure why we set the version explicitly here, so we may need other changes to solve this issue.

[kiview]

Hi folks, we are aware of this issue and will provide workarounds and a fix shortly.

Edit:
The workaround mentioned by @tomas-forsman should be fine:
#11212 (comment)

[omasseau]

Hi folks, we are aware of this issue and will provide workarounds and a fix shortly.

Edit: The workaround mentioned by @tomas-forsman should be fine: #11212 (comment)

I don't undestand here what is exactly $HOME.
Just addind the file .docker-java.properties at the root of the java project is enough ?

[kiview]

@omasseau That is your user home directory.

As an alternative workaround, rolling back the Docker engine version to 28.x should also work.

[dirk-janssen]

Alternative that works for us
@BeforeAll static void setup() { System.setProperty("api.version", "1.44"); }

[jebeaudet]

If you run with failsafe, you can also do this

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <configuration>
        <systemPropertyVariables>
            <api.version>1.44</api.version>
        </systemPropertyVariables>
    </configuration>
</plugin>

This was tested with testcontainers versions 1.21.3 and 2.0.1.