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

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

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

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.

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.

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

api.version=1.44

relates to #11210

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.

@tomas-forsman

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)

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 ?

@omasseau

@omasseau That is your user home directory.

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

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

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.

[BUILD] Fix docker client API issue

Bump testcontainers from 1.20.6 to 2.0.2. (#562)

upgrade Testcontainers

[BUILD] Fix docker client API issue

Upgrading TestContainer library version due to incompatibility with t…

Fixing MariaDB schema differ which wasn't finding index direction: ac…

AK / CP / Testcontainers dependency upgrades (#118)

Upgrade testcontainers version to 2.0.2 for Docker v29+ compatibility

If you run with failsafe, you can also do this
org.apache.maven.plugins maven-failsafe-plugin 1.44 This was tested with `testcontainers` versions 1.21.3 and 2.0.1.

So happy you made this post, just saved our team big time!!!

Also works with Surefire plugin:

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

The workaround for Gradle:

tasks.named('test') {
    systemProperty("api.version", "1.44")
}

In July 2026 it's still the problem.

@evishnevskiy

@evishnevskiy which testcontainers version do you mean? Are there any blockers on your side to update to the latest 2.0.5?

Navigation Menu

Repository navigation

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

Module

Testcontainers version

Using the latest Testcontainers version?

Host OS

Host Arch

Docker version

What happened?

Relevant log output

Additional Information

44 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

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

Description

Module

Testcontainers version

Using the latest Testcontainers version?

Host OS

Host Arch

Docker version

What happened?

Relevant log output

Additional Information

Activity

matzegebbe commented on Nov 11, 2025

msstaicu commented on Nov 11, 2025

msstaicu commented on Nov 11, 2025

tomas-forsman commented on Nov 11, 2025

leun4m commented on Nov 11, 2025

KengoTODA commented on Nov 11, 2025

kiview commented on Nov 11, 2025

omasseau commented on Nov 11, 2025

kiview commented on Nov 11, 2025

dirk-janssen commented on Nov 11, 2025

jebeaudet commented on Nov 11, 2025

44 remaining items

slcscooter commented on Feb 12, 2026

artemyakovenko28 commented on Feb 17, 2026

soid commented on Feb 17, 2026

evishnevskiy commented on Jul 21, 2026

seregamorph commented on Jul 21, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions