Skip to content
javahacks.dev
Testing

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.

6 min read
Summarize in AI
Flat illustration of a log with a failing line and a wrench, with the Docker, Apache Maven, Spring and Gradle logos.

The test fails immediately, before any container starts:

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

Testcontainers 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?

Shell
docker ps
docker context ls

If 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:

RuntimeTypical 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:

Shell
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
./mvnw test

With 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:

properties
docker.host=unix:///Users/ana/.colima/default/docker.sock

Step 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:

YAML
container:
  image: maven:3-eclipse-temurin-25
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Mounting 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

java
@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.

Text
Could not find a valid Docker environment. Please see logs and check configuration

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

Shell
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:

properties
docker.host=unix:///Users/me/.docker/run/docker.sock

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

YAML
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 verify

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

java
@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.

java
@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.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.