Spring Boot Testcontainers "Could not find a valid Docker environment" in CI
Testcontainers probes for a working Docker daemon before starting containers and found none. In CI this means the runner has no Docker socket, or the JVM cannot reach it, so no Postgres/Kafka/Redis container can start.
What this error means
A Testcontainers-backed @SpringBootTest fails at startup with "Could not find a valid Docker environment. Please see logs and check configuration".
org.testcontainers.dockerclient.DockerClientProviderStrategy: Could not find a valid
Docker environment. Please see logs and check configuration
java.lang.IllegalStateException: Could not find a valid Docker environment.Common causes
No Docker daemon on the runner
The runner image has no Docker, or the socket is not mounted, so Testcontainers cannot launch containers.
The JVM cannot reach the Docker socket
DOCKER_HOST is unset or points at an unreachable endpoint, so the client cannot connect even when a daemon exists.
How to fix it
Use a runner with Docker available
GitHub-hosted Ubuntu runners include Docker; ensure the job runs on one and the socket is reachable.
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: ./gradlew testPoint Testcontainers at the daemon
Set DOCKER_HOST when the socket is non-default so the client connects.
env:
DOCKER_HOST: unix:///var/run/docker.sockHow to prevent it
- Run Testcontainers jobs on runners that provide a Docker daemon.
- Verify the Docker socket is reachable before the test step.
- Fall back to a service container or H2 where Docker is unavailable.