Maaz Zindani

Loading the index…

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

Testcontainers cannot start the Ryuk container when Docker runs on Colima

Errortests fail when Testcontainers creates its testcontainers/ryuk container

Short answer

Testcontainers does not find Colima's Docker socket the way it finds Docker Desktop's. Start Colima with a network address and set the three variables the Testcontainers docs list: DOCKER_HOST to the Colima socket, TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE, and TESTCONTAINERS_HOST_OVERRIDE. Then rerun the tests.

  • Applies to Testcontainers for Java 1.2x, Colima, macOS 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check what the shell sees. If DOCKER_HOST is empty, the test process falls back to its default strategies, not to Colima.

    echo "$DOCKER_HOST"
    ls ~/.colima/default/docker.sock
  2. 2Match what you see, then jump to its fix

    1. 1DOCKER_HOST is empty, or points at a Docker Desktop socketDOCKER_HOST does not point at the Colima socketFix
    2. 2DOCKER_HOST is right but the Ryuk container still fails to be created or reachedColima started without a network address, and the override variables are missingFix

What does the error look like?

  • tests fail when Testcontainers creates its testcontainers/ryuk container
  • docker ps works in the terminal but the same daemon is not found from the test JVM
  • everything works on Docker Desktop and breaks after switching to Colima

Cause 1 of 2

DOCKER_HOST does not point at the Colima socket

1Check

Testcontainers tries environment variables first: DOCKER_HOST, DOCKER_TLS_VERIFY and DOCKER_CERT_PATH. If DOCKER_HOST is unset it uses defaults that do not know about Colima.

env | grep DOCKER
ls -l ~/.colima/default/docker.sock

2Fix

Point DOCKER_HOST at the Colima socket in the shell or IDE run configuration that starts the tests.

export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

3Verify

docker ps answers from the same shell, then run the tests from it.

docker ps

Confirmed by java.testcontainers.org

Did this fix it?

Cause 2 of 2

Colima started without a network address, and the override variables are missing

1Check

The Testcontainers docs for Colima ask for colima start --network-address, and for TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE and TESTCONTAINERS_HOST_OVERRIDE as well as DOCKER_HOST.

colima ls -j

2Fix

Restart Colima with a network address and export the three variables from the Testcontainers page. This needs jq for reading the address.

colima stop
colima start --network-address
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
export TESTCONTAINERS_HOST_OVERRIDE=$(colima ls -j | jq -r '.address')
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

3Verify

Run the test class again from the same shell.

./gradlew test

Confirmed by java.testcontainers.org

Did this fix it?

How do I stop it coming back?

  • Put the three exports in the shell profile or in the IDE run configuration, so tests do not depend on how they were started.
  • Run docker ps in the same environment as the tests before you debug Testcontainers itself.

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.