Testcontainers "Could not connect to Ryuk" - Fix in CI
By Kaveh Alemi·Latchkey
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.
junit
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 out
Diagnose it: resolve the effective POM first
Maven merges parent POMs, profiles, and settings before it builds anything. The configuration causing your failure is frequently inherited or activated by a profile that is on locally and off in CI.
Terminal
# the fully resolved configuration Maven will actually use
mvn help:effective-pom | head -60
# which profiles are active here vs on your machine?
mvn help:active-profiles
# full error, offline-safe, no colour codes to confuse the log
mvn -B -e -X <goal> 2>&1 | tail -60
Common 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.
Terminal
docker info # daemon reachable?
docker run --rm hello-world # sanity check
Disable 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.
Terminal
# env for ephemeral, single-use runners
TESTCONTAINERS_RYUK_DISABLED=true
Point Testcontainers at the right Docker host
Set the host/socket explicitly when the default probe fails.
Terminal
# ~/.testcontainers.properties or env
DOCKER_HOST=unix:///var/run/docker.sock
How 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.
Frequently asked questions
What causes Testcontainers "Could not connect to Ryuk"?
There are 3 common causes: ryuk cannot bind the docker socket/port, docker daemon slow or starting, and network policy blocks the ryuk handshake. On a restricted runner, the mapped Ryuk port is unreachable, so the resource reaper handshake times out.
How do I fix Testcontainers "Could not connect to Ryuk"?
There are 3 fixes depending on which cause you have: ensure a working docker environment, disable ryuk only when cleanup is otherwise handled, and point testcontainers at the right docker host. Work through them in order, since the first is the most common.
What does Testcontainers "Could not connect to Ryuk" actually mean?
Tests fail at startup with Could not connect to Ryuk at ...
How do I stop Testcontainers "Could not connect to Ryuk" happening again?
Ensure the Docker daemon is healthy before Testcontainers-based tests start. The prevention section lists 3 changes that keep it from recurring.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
