Testcontainers "Could not find a valid Docker environment" in CI

By Daniel Zoghalchali·Latchkey

Testcontainers probes the standard Docker locations (the DOCKER_HOST env var, the default unix socket, and the docker context) and none answered. Without a reachable daemon it cannot start any container, so it aborts before your test runs.

What this error means

Test startup fails with "Could not find a valid Docker environment. Please see logs and check the configuration". It happens on runners where Docker is not installed, not started, or the socket path differs from the default.

Testcontainers

org.testcontainers.dockerclient.DockerClientProviderStrategy - Could not find a valid Docker environment.
Please see logs and check the configuration
java.lang.IllegalStateException: Could not find a valid Docker environment.

Diagnose it: produced, uploaded, or mapped?

Third-party integrations fail at one of three points, and the symptom is the same for all of them: the report was never produced, the upload was rejected, or the service could not map the paths back to your repository.

Terminal

ls -la <report-dir>/ && head -5 <report-file>
grep -c . <report-file> || echo "empty report"
# absolute paths in a report break server-side file mapping
grep -m3 -E "^(SF:|<file)" <report-file>

Common causes

No Docker daemon is running on the runner

Some CI runners (self-hosted, minimal containers) do not have Docker installed or started, so there is no socket for Testcontainers to reach.

The socket path differs from the default

Testcontainers looks at unix:///var/run/docker.sock by default. If the daemon listens elsewhere and DOCKER_HOST is unset, discovery fails.

How to fix it

Ensure Docker is available and point DOCKER_HOST at it

On GitHub-hosted ubuntu runners Docker is preinstalled; confirm the job runs on such a runner, not inside a container without Docker.
If the daemon listens on a non-default socket, export DOCKER_HOST so Testcontainers finds it.
Re-run and confirm the strategy log now reports a working environment.

Terminal

export DOCKER_HOST=unix:///var/run/docker.sock
docker info   # must succeed before tests run

Run the test job on a runner with Docker

If you run tests inside a container, mount the host Docker socket or use a runner image that provides a daemon so Testcontainers has something to talk to.

.github/workflows/ci.yml

jobs:
  test:
    runs-on: ubuntu-latest   # Docker preinstalled and running

How to prevent it

Run Testcontainers tests on runners that provide a working Docker daemon.
Set DOCKER_HOST explicitly when the socket is not at the default path.
Add a docker info smoke check before the test step so failures are obvious.

Frequently asked questions

What causes Testcontainers "Could not find a valid Docker environment" in CI?

There are 2 common causes: no docker daemon is running on the runner and the socket path differs from the default. Some CI runners (self-hosted, minimal containers) do not have Docker installed or started, so there is no socket for Testcontainers to reach.

How do I fix Testcontainers "Could not find a valid Docker environment" in CI?

There are 2 fixes depending on which cause you have: ensure docker is available and point docker_host at it and run the test job on a runner with docker. Work through them in order, since the first is the most common.

What does Testcontainers "Could not find a valid Docker environment" in CI actually mean?

Test startup fails with "Could not find a valid Docker environment.

How do I stop Testcontainers "Could not find a valid Docker environment" in CI happening again?

Run Testcontainers tests on runners that provide a working Docker daemon. The prevention section lists 3 changes that keep it from recurring.