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

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.

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.