# Testcontainers "Could not connect to Ryuk" - Fix in CI

> Fix Testcontainers "Could not start container" / "Timed out waiting for container ... Ryuk" in CI - the Ryuk resource-reaper sidecar could not be reached, usually a Docker-in-CI networking or socket issue.

Source: https://latchkey.dev/learn/java-jvm/testcontainers-ryuk-could-not-connect-in-ci  
Updated: 2026-06-26

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.

## 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
```

> Always pass `-B` (batch mode) in CI. Without it Maven emits interactive progress output that bloats logs and can hang on a prompt.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt