Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Testcontainers fails with Could not connect to Ryuk at localhost

Errorjava.lang.IllegalStateException: Could not connect to Ryuk at localhost:49167

Short answer

Ryuk is the helper container Testcontainers starts to clean up after tests. This error means the test JVM started it but could not open a connection to its mapped port. Check which host and Docker socket Testcontainers uses, then set the host override, allow a privileged Ryuk, or turn Ryuk off where the platform cleans up itself.

  • Applies to Testcontainers for Java 1.21, Docker Engine 28, JDK 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the test once, then list the containers while it is running. This shows whether Ryuk started and which host port Docker gave it.

    docker ps --filter ancestor=testcontainers/ryuk --format '{{.Names}} {{.Ports}}'
  2. 2Match what you see, then jump to its fix

    1. 1Ryuk is running in docker ps with a port mapping, but the JVM still cannot connect to localhost on that portThe mapped port is not reachable at the host name Testcontainers choseFix
    2. 2The connection to Ryuk fails and your environment is one where containers need extra privilegesRyuk must run in privileged mode in this environmentFix
    3. 3The platform (a locked-down CI runner, for example) does not allow Ryuk to start at allThe environment forbids privileged containers or cleans up by itselfFix

What does the error look like?

  • java.lang.IllegalStateException: Could not connect to Ryuk at localhost:49167
  • docker ps shows a testcontainers/ryuk container while the test fails

Cause 1 of 3

The mapped port is not reachable at the host name Testcontainers chose

1Check

Testcontainers detects where Docker runs and connects to the ports on that host. When Docker runs in a VM, a remote machine or a different network namespace, the guess can be wrong. Compare it with the address you use to reach published ports yourself.

echo "$DOCKER_HOST"
docker context ls

2Fix

Tell Testcontainers the host that exposes the container ports, and if needed the socket path, with the documented override variables.

export TESTCONTAINERS_HOST_OVERRIDE=192.168.64.2
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock

3Verify

Run the tests again from the same shell.

./mvnw test

Confirmed by java.testcontainers.org

Did this fix it?

Cause 2 of 3

Ryuk must run in privileged mode in this environment

1Check

Some Docker setups need Ryuk to run with --privileged. The Testcontainers configuration lists a property for that in the file .testcontainers.properties in your home folder.

cat ~/.testcontainers.properties
docker ps -a --filter ancestor=testcontainers/ryuk

2Fix

Enable the documented property, which starts Ryuk as a privileged container.

echo "ryuk.container.privileged=true" >> ~/.testcontainers.properties

3Verify

Run the tests; Ryuk should stay up for the whole run.

docker ps --filter ancestor=testcontainers/ryuk

Confirmed by java.testcontainers.org

Did this fix it?

Cause 3 of 3

The environment forbids privileged containers or cleans up by itself

1Check

Ask whether the environment already removes containers after every job. Only then is it safe to run without Ryuk.

env | grep TESTCONTAINERS

2Fix

Turn Ryuk off with the documented environment variable. Testcontainers still cleans up when the JVM shuts down normally, but not after kill -9.

export TESTCONTAINERS_RYUK_DISABLED=true

3Verify

Run the tests and check that no testcontainers/ryuk container is started.

./mvnw test
docker ps -a --filter ancestor=testcontainers/ryuk

Confirmed by java.testcontainers.org

Did this fix it?

How do I stop it coming back?

  • Put the Testcontainers settings in ~/.testcontainers.properties or in the CI job environment, so every run uses the same values.
  • Run docker ps in the same shell as the tests before blaming the library.
  • Disable Ryuk only on runners that destroy their containers after each job.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.