Testcontainers fails with Could not connect to Ryuk at localhost
java.lang.IllegalStateException: Could not connect to Ryuk at localhost:49167Short 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.
Fix it fast
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}}'2Match what you see, then jump to its fix
- 1
Ryuk 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
The connection to Ryuk fails and your environment is one where containers need extra privilegesRyuk must run in privileged mode in this environmentFix - 3
The 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
- 1
What does the error look like?
java.lang.IllegalStateException: Could not connect to Ryuk at localhost:49167docker 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 ls2Fix
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.sock3Verify
Run the tests again from the same shell.
./mvnw testConfirmed by java.testcontainers.org
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/ryuk2Fix
Enable the documented property, which starts Ryuk as a privileged container.
echo "ryuk.container.privileged=true" >> ~/.testcontainers.properties3Verify
Run the tests; Ryuk should stay up for the whole run.
docker ps --filter ancestor=testcontainers/ryukConfirmed by java.testcontainers.org
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 TESTCONTAINERS2Fix
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=true3Verify
Run the tests and check that no testcontainers/ryuk container is started.
./mvnw test
docker ps -a --filter ancestor=testcontainers/ryukConfirmed by java.testcontainers.org
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
Servers
Testcontainers cannot start the Ryuk container when Docker runs on Colima
docker ps works in the terminal but the same daemon is not found from the test JVM
Testcontainers does not find Colima's Docker socket the way it finds Docker Desktop's.
2 causes, each with a fixServers
The Java SDK finds no AWS credentials on an EC2 instance or in a container on it
InstanceProfileCredentialsProvider()
The SDK walks a fixed list of credential sources and the EC2 instance role is the last one.
3 causes, each with a fixServers
docker build stops at COPY because the file is not in the build context
ERROR: failed to solve: failed to compute cache key:
COPY can only read files that are inside the build context, the folder you pass to docker build.
3 causes, each with a fixServers
Docker build fails to resolve the openjdk slim-buster base image
failed to resolve source metadata for docker.io/library/openjdk:21-slim-buster
The tag you named does not exist any more.
2 causes, each with a fixServers
A Java container dies at start with 'insufficient memory' or errno=12
os::commit_memory failed; error='Not enough space' (errno=12)
The JVM asked the operating system for more memory than the container is allowed to use.
3 causes, each with a fixServers
MongoDB says Authentication failed from a Java app against a Docker container
MongoCommandException: Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017
Error 18 means MongoDB found no matching user in the database it checked.
4 causes, each with a fix