Testcontainers "Could not start Ryuk resource reaper" in CI

Testcontainers starts a small "Ryuk" container that reaps leftover containers after the run. When Ryuk cannot start or the test process cannot connect back to it, startup fails. On locked-down CI runners the standard remedy is to disable Ryuk.

What this error means

Startup fails with "Could not start Ryuk resource reaper" or a connection error to the Ryuk container. It is common on runners that block the privileged sidecar or its callback port.

org.testcontainers.utility.ResourceReaper - Could not start Ryuk resource reaper
java.lang.IllegalStateException: Could not connect to Ryuk at <ip>:<port>

Common causes

The runner blocks the Ryuk container or its callback

Restricted or nested environments prevent starting the Ryuk sidecar or block the port the test process uses to talk to it.

Socket sharing limits the reaper

When the Docker socket is mounted from the host, the reaper container may not be reachable from the test process in the way it expects.

How to fix it

Disable Ryuk when the runner cannot host it

On ephemeral CI runners where containers are cleaned up by the runner anyway, set TESTCONTAINERS_RYUK_DISABLED=true so no reaper is needed.

env:
  TESTCONTAINERS_RYUK_DISABLED: true

Keep Ryuk but allow its container and port

If you want automatic reaping, ensure the runner can start privileged helper containers and does not block the Ryuk callback port.

How to prevent it

• Disable Ryuk on ephemeral runners that discard the environment after each job.
• Allow the Ryuk container and its callback port when keeping reaping on.
• Set the env consistently so behavior is identical across jobs.

Related guides