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

Testcontainers needs a reachable Docker daemon to launch its containers. "Could not find a valid Docker environment" means it could not connect - no daemon running, a wrong/socket-less DOCKER_HOST, or insufficient permissions on the runner.

What this error means

Tests using @Testcontainers fail in setup with Could not find a valid Docker environment. Please see logs and check the configuration. Often the daemon is not started or the socket is unreachable.

junit

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

Common causes

No Docker daemon available on the runner

The runner has no Docker installed/started, or the user cannot access the Docker socket, so Testcontainers cannot connect.

Wrong DOCKER_HOST or transient socket blip

A misconfigured DOCKER_HOST/TESTCONTAINERS_* var points at nothing, or the daemon was briefly not ready when tests started (transient).

How to fix it

Ensure Docker is present and reachable

Confirm the daemon is up before tests run; on hosted Linux runners Docker is usually available.

.github/workflows/ci.yml

- run: docker info        # must succeed before tests
- run: ./gradlew test     # Testcontainers connects to the daemon

Fix host/permissions configuration

Verify DOCKER_HOST (and any TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE) point at the real socket.
Ensure the job user has access to the Docker socket.
On self-managed runners, start the Docker service in a setup step.

How to prevent it

Run Testcontainers on runners with a ready Docker daemon, assert docker info early, and keep DOCKER_HOST/socket configuration correct.