Testcontainers "Could not connect to Ryuk" - Fix in CI
Testcontainers starts a small "Ryuk" container that cleans up test containers after the JVM exits. When Ryuk cannot be reached - a Docker socket the runner cannot bind, a restricted network, or a slow daemon - container startup fails before any test runs.
What this error means
Tests fail at startup with Could not connect to Ryuk at ... or Timed out waiting for container port to open (... ryuk ...). The failure is in Testcontainers init, not your test logic, and often clears on a retry.
org.testcontainers.containers.ContainerLaunchException: Could not connect to
Ryuk at localhost:32769
at org.testcontainers.utility.RyukResourceReaper.start...
Caused by: java.net.SocketTimeoutException: connect timed outCommon causes
Ryuk cannot bind the Docker socket/port
On a restricted runner, the mapped Ryuk port is unreachable, so the resource reaper handshake times out.
Docker daemon slow or starting
A cold daemon on a fresh runner is not ready when Testcontainers tries to start Ryuk, causing a connect timeout.
Network policy blocks the Ryuk handshake
Locked-down networking blocks the loopback/port Ryuk uses for its connection.
How to fix it
Ensure a working Docker environment
Confirm the daemon is up and the socket is reachable before tests run.
docker info # daemon reachable?
docker run --rm hello-world # sanity checkDisable Ryuk only when cleanup is otherwise handled
If the runner is ephemeral and torn down per job, you can skip Ryuk to avoid the handshake.
# env for ephemeral, single-use runners
TESTCONTAINERS_RYUK_DISABLED=truePoint Testcontainers at the right Docker host
Set the host/socket explicitly when the default probe fails.
# ~/.testcontainers.properties or env
DOCKER_HOST=unix:///var/run/docker.sockHow to prevent it
- Ensure the Docker daemon is healthy before Testcontainers-based tests start.
- On ephemeral single-use runners, consider disabling Ryuk safely.
- Pin the Docker host/socket so the probe does not race a cold daemon.