Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Testcontainers (Java) says it could not find a valid Docker environment on a Mac

Errorjava.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configuration

Short 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.

  • Applies to Testcontainers for Java 1.x and 2.x, Docker Desktop for Mac, Docker Engine 28 and 29
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2echo prints a path or address, and docker info works with a different oneDOCKER_HOST points at another runtime, or a stale valueFix
    3. 3Client 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

What does the error look like?

  • java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configuration
  • Client 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.sock

2Fix

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 used

3Verify

The socket exists and the daemon answers through it.

ls -l /var/run/docker.sock
docker info

Confirmed by docs.docker.com

Did this fix it?

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.properties

2Fix

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=MyContainerTest

Confirmed by java.testcontainers.org

Did this fix it?

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.44

3Verify

Re-run the failing test class.

./mvnw -q test -Dtest=MyContainerTest

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.