Fix Testcontainers Could Not Find a Valid Docker Environment
Fix the Testcontainers error about a missing Docker environment by starting the daemon, pointing at the right socket and updating an old client.

The test fails immediately, before any container starts:
java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configurationTestcontainers tries several ways to find a Docker daemon: environment variables, the default Unix socket, the Docker Desktop and Colima sockets. It gives up if none responds. The log above the exception lists each attempt and its failure, and that list is the diagnosis. How Testcontainers fits into tests is covered in a practical Java testing strategy.
Step 1: does Docker work in this shell?
docker ps
docker context lsIf docker ps fails, Testcontainers will too. Start Docker Desktop, or the daemon (sudo systemctl start docker on Linux). If it works, continue; the tests are looking somewhere else.
Step 2: the socket is not where Testcontainers looks
The default is /var/run/docker.sock. Some runtimes put it elsewhere:
| Runtime | Typical socket |
|---|---|
| Docker Desktop (macOS) | ~/.docker/run/docker.sock, with /var/run/docker.sock linked if enabled |
| Colima | ~/.colima/default/docker.sock |
| Rancher Desktop | ~/.rd/docker.sock |
| Podman | $XDG_RUNTIME_DIR/podman/podman.sock |
Point at the socket for the test run:
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
./mvnw testWith Docker Desktop, check the setting "Allow the default Docker socket to be used" in the advanced options. With Podman, enable the user socket (systemctl --user enable --now podman.socket) and set TESTCONTAINERS_RYUK_DISABLED=true if the resource reaper cannot start.
You can also persist the strategy in ~/.testcontainers.properties:
docker.host=unix:///Users/ana/.colima/default/docker.sockStep 3: the daemon rejects an old client
Docker Engine releases raise the minimum API version they accept from time to time. An old Testcontainers release speaks an old API version and receives an error such as a client version being too old. The Testcontainers log shows the daemon's response. The fix is to update Testcontainers (and with Spring Boot, the managed version via the Boot upgrade) rather than lowering the daemon's minimum.
Step 4: CI
A hosted CI runner with Docker (GitHub Actions' ubuntu-latest) needs nothing. If the build runs inside a container, give it the socket:
container:
image: maven:3-eclipse-temurin-25
volumes:
- /var/run/docker.sock:/var/run/docker.sockMounting the socket gives the job control over the host's Docker, so treat it as privileged. Kubernetes-based runners need Docker-in-Docker or a Testcontainers Cloud setup. The CI side is described in setting up CI for a Java project.
Keep tests from failing on machines without Docker
@Testcontainers(disabledWithoutDocker = true)
class OrderRepositoryTest { }The class is skipped instead of failed when Docker is absent. This is convenient for a contributor's laptop and dangerous in CI, where a skipped suite looks green. Decide on purpose.
The strategy Testcontainers uses, and what a test showed
The message reads as if Docker were missing, and it often means Testcontainers could not reach a daemon by any of its strategies. It tries them in turn: the DOCKER_HOST environment variable, the docker.host property in ~/.testcontainers.properties, the default Unix socket /var/run/docker.sock, and a few well-known alternatives such as the Docker Desktop and Rancher Desktop sockets. The exception is thrown only if all of them fail.
That ordering produced a surprising result in a test. With Docker Desktop running, the variable DOCKER_HOST=tcp://127.0.0.1:9, pointing at a port where nothing listens, did not break the test: Testcontainers tried the TCP address, failed, fell back to the default socket and ran the test. The test passed with a wrong DOCKER_HOST. The error is raised when no strategy works, so a wrong variable on a machine that otherwise has a reachable socket stays hidden, and a variable that is wrong on a machine with no socket gives you the message, with the failed attempts in the log above it.
Could not find a valid Docker environment. Please see logs and check configurationRead the log lines above this line first. Each strategy prints the reason it failed, such as UnixSocketClientProviderStrategy: failed with exception ... (java.io.IOException: No such file or directory). Those lines identify which socket was tried and which error came back.
Check the shell, then the socket
Do the first test outside Java, in the same shell that runs the build.
docker version --format '{{.Server.Version}}'
docker context ls
ls -l /var/run/docker.sock ~/.docker/run/docker.sock 2>/dev/null
echo "$DOCKER_HOST"If docker version fails, the daemon is not running, and no Testcontainers setting will help: start Docker Desktop, or the service on Linux. If it works, compare the socket it uses with the one Testcontainers tries. Docker Desktop on macOS and some Linux rootless setups put the socket in the home directory, and docker context ls shows the active endpoint. Point Testcontainers at it in ~/.testcontainers.properties, which applies to every project:
docker.host=unix:///Users/me/.docker/run/docker.sockOn Linux, if the file exists but permission is denied, the user is not in the docker group. Add it with sudo usermod -aG docker $USER and log in again, because group membership is read at login.
CI is a different environment
On a hosted CI runner the daemon is present or not depending on the executor, and in a container-based runner you must provide access. For GitHub Actions on ubuntu-latest, Docker is installed and nothing needs configuring. For GitLab CI with the Docker executor, mount the socket or use the Docker-in-Docker service and set the host to match.
test:
image: maven:3-eclipse-temurin-25
services:
- docker:dind
variables:
DOCKER_HOST: tcp://docker:2375
DOCKER_TLS_CERTDIR: ""
TESTCONTAINERS_HOST_OVERRIDE: docker
script:
- mvn -B verifyTESTCONTAINERS_HOST_OVERRIDE tells Testcontainers which host name to use for mapped ports, since containers in a Docker-in-Docker setup are reachable at the DinD host, not at localhost.
Let the build run on machines without Docker
Some machines cannot run containers, a locked-down laptop or a constrained runner. Rather than let the whole test suite fail, skip the container tests there with a JUnit condition, and keep unit tests running.
@Testcontainers(disabledWithoutDocker = true)
class OrderRepositoryIT { }With disabledWithoutDocker, JUnit reports the tests as skipped instead of failed when no Docker is found. Make sure your CI environment has Docker, and fails if the skipped count is non-zero, or the container tests will silently stop running there.
Document the setup for new team members
The error is mostly met by someone setting up a machine. Put the requirements in the README in three lines: which container runtime is supported and how to install it, the command that proves it works (docker run --rm hello-world), and where Testcontainers settings live for each operating system. Add a test, run at the start of the suite, that fails early with a clear message rather than letting fifty tests each print the same long error.
@BeforeAll
static void dockerAvailable() {
assumeTrue(DockerClientFactory.instance().isDockerAvailable(), "Docker is required for these tests");
}Use an assumption for tests that may be skipped on some machines, and a failure for the CI job, where Docker must be present. The two policies differ on purpose: a developer without Docker should still be able to run the unit tests, and the pipeline should never pass with the container tests silently skipped.
Where this does not apply
If Docker is reachable and a container fails to start, the error is different: an image pull failure, a port, or a health check timeout. Read the container log from the Testcontainers output. The difference between this kind of test and a unit test is in unit vs integration tests. The Testcontainers documentation on custom configuration lists every environment variable and property, and the Docker documentation on contexts explains how the CLI chooses a daemon.


