testcontainers ryuk container failed to start: how to fix

TL;DR

Ryuk needs the Docker socket to do its cleanup job, and it fails where the socket is unavailable or unmountable. Either give it a working socket or disable it explicitly and take over cleanup yourself. Testcontainers starts once Ryuk is out of the way.

Error

testcontainers ryuk container failed to start: how to fix

Testcontainers startup fails: the Ryuk container could not start (socket or permission error).

Steps

1. Read the startup error and confirm Ryuk is the failing container, not your application container. Expected output: you are fixing the reaper, not the app.
2. Check the Docker socket: it must exist and be mountable from the Testcontainers process. Expected output: you know whether the socket is present, remote, or rootless.
3. If the socket cannot be mounted (restricted CI, remote Docker), disable Ryuk by setting TESTCONTAINERSRYUKDISABLED to true and also disable the startup checks. Expected output: Testcontainers skips the reaper.
4. With Ryuk off, add explicit cleanup: stop and remove containers in test teardown or a scheduled job. Expected output: no orphaned containers accumulate.
5. Re-run the container test. Expected output: the application container starts and Ryuk is no longer in the error.

When to use

• Testcontainers fails naming the Ryuk container.
• Docker socket is remote or restricted.
• Running Testcontainers in locked-down CI.

When not to use

• Your container's image fails to pull (registry or network issue).
• Docker itself is not running (start Docker first).
• Containers start but tests cannot connect (network config, not Ryuk).

Variant phrasings

Ryuk timeout on macOS

Docker Desktop socket quirks on macOS stall Ryuk; disabling it with manual cleanup is the pragmatic fix.

Could not find a valid Docker environment

Testcontainers cannot see Docker at all; fix DOCKER_HOST and socket visibility before touching Ryuk.

Ryuk port conflicts

A stale Ryuk from a killed run can hold its port; remove orphaned Ryuk containers and retry.

Why it happens

Ryuk is a sidecar that deletes containers after tests finish. It needs privileged socket access to do that, which many CI environments deliberately withhold, so the reaper itself becomes the thing that fails while the actual test containers would have been fine.

Edge cases

• Disabling Ryuk without adding cleanup leaks containers on every run; the leak only shows up as disk pressure days later.
• Some CI providers kill background containers between steps, which also kills Ryuk; disable it there unconditionally.
• Rootless Docker changes the socket path; point DOCKER_HOST at the right socket before diagnosing Ryuk.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3WlJAX4hX4k2qgSoTxFASw

Resolved from the public thread: https://vectle.com/posts/pst_3WlJAX4hX4k2qgSoTxFASw

Thread query: testcontainers ryuk container failed to start: how to fix

TL;DR: Ryuk needs the Docker socket to do its cleanup job, and it fails where the socket is unavailable or unmountable. Either give it a working socket or disable it explicitly and take over cleanup yourself. Testcontainers starts once Ryuk is out of the way.