Testcontainers (Java) says it could not find a valid Docker environment on a Mac
java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configurationShort answer
Testcontainers tried every way it knows to reach Docker and none answered. On a Mac that is usually one of three things: Docker Desktop is not running or its default socket is off, DOCKER_HOST points somewhere else than your runtime, or a new Docker Engine rejects the client's old API version.
Fix it fast
1Find out which cause you have
Run these from the same terminal or IDE that runs the tests. If docker info fails here, Testcontainers cannot work either. Then read the test log: it lists each strategy it tried and why it failed.
docker info docker version echo "$DOCKER_HOST"2Match what you see, then jump to its fix
- 1
The log shows a missing /var/run/docker.sock while docker info works only through a different contextDocker Desktop is stopped, or its default socket is not createdFix - 2
echo prints a path or address, and docker info works with a different oneDOCKER_HOST points at another runtime, or a stale valueFix - 3
Client version 1.32 is too old. Minimum supported API version is 1.44 in the strategy errors, with Docker Engine 29.0 to 29.2Docker Engine 29 refuses the client's old API versionFix
- 1
What does the error look like?
java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configurationClient version 1.32 is too old. Minimum supported API version is 1.44
Cause 1 of 3
Docker Desktop is stopped, or its default socket is not created
1Check
Docker Desktop on a Mac can run without creating /var/run/docker.sock. Check whether that path exists.
ls -l /var/run/docker.sock2Fix
Start Docker Desktop. In Settings > Advanced, turn on the option that allows the default Docker socket to be used; it creates /var/run/docker.sock for third-party clients.
# Docker Desktop > Settings > Advanced > Allow the default Docker socket to be used3Verify
The socket exists and the daemon answers through it.
ls -l /var/run/docker.sock
docker infoConfirmed by docs.docker.com
Cause 2 of 3
DOCKER_HOST points at another runtime, or a stale value
1Check
Testcontainers reads DOCKER_HOST first, then its defaults, then Docker Machine. A wrong or left-over DOCKER_HOST wins over everything after it.
echo "$DOCKER_HOST"
cat ~/.testcontainers.properties2Fix
Unset it for Docker Desktop. For Colima or Rancher Desktop, set it to that runtime's socket, as the Testcontainers docs show.
unset DOCKER_HOST
# Colima instead:
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"3Verify
Run one test class from the same shell and look for a container start in the log.
./mvnw -q test -Dtest=MyContainerTestConfirmed by java.testcontainers.org
Cause 3 of 3
Docker Engine 29 refuses the client's old API version
1Check
Docker Engine 29.0.0 raised the minimum API version to 1.44. Testcontainers uses an older default when none is set. The 29.3.0 release notes say the minimum went back down to 1.40.
docker version --format '{{.Server.Version}}'2Fix
Pin the client API version in the user-level docker-java properties file, or update Testcontainers or Docker. Remove the pin once both sides are current.
# ~/.docker-java.properties
api.version=1.443Verify
Re-run the failing test class.
./mvnw -q test -Dtest=MyContainerTestConfirmed by docs.docker.com
How do I stop it coming back?
- Keep Docker Desktop and the Testcontainers version updated together.
- Set DOCKER_HOST in one place only, such as your shell profile, and not in IDE run configurations.
- Run docker info in CI before the tests so a missing runtime shows up in one clear line.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Testcontainers (Java) fails with 'docker-machine executable was not found on PATH'
docker-machine executable was not found on PATH
This message is the last step of a search.
3 causes, each with a fixServers
The Java SDK finds no AWS credentials on an EC2 instance or in a container on it
InstanceProfileCredentialsProvider()
The SDK walks a fixed list of credential sources and the EC2 instance role is the last one.
3 causes, each with a fixServers
docker build stops at COPY because the file is not in the build context
ERROR: failed to solve: failed to compute cache key:
COPY can only read files that are inside the build context, the folder you pass to docker build.
3 causes, each with a fixServers
Docker build fails to resolve the openjdk slim-buster base image
failed to resolve source metadata for docker.io/library/openjdk:21-slim-buster
The tag you named does not exist any more.
2 causes, each with a fixServers
A Java container dies at start with 'insufficient memory' or errno=12
os::commit_memory failed; error='Not enough space' (errno=12)
The JVM asked the operating system for more memory than the container is allowed to use.
3 causes, each with a fixServers
MongoDB says Authentication failed from a Java app against a Docker container
MongoCommandException: Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017
Error 18 means MongoDB found no matching user in the database it checked.
4 causes, each with a fix