Maaz Zindani

Loading the index…

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

Testcontainers (Java) fails with 'docker-machine executable was not found on PATH'

Errordocker-machine executable was not found on PATH

Short answer

This message is the last step of a search. Testcontainers first checks DOCKER_HOST and its variables, then the default local settings, and only then tries Docker Machine. If you see the docker-machine error, the first two found no running Docker. Start the runtime, or set DOCKER_HOST to its socket.

  • Applies to Testcontainers for Java 1.x, Docker Engine 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check that the Docker CLI can reach a running daemon from the same shell that runs the tests, and print the variable Testcontainers reads first.

    docker info
    echo "$DOCKER_HOST"
  2. 2Match what you see, then jump to its fix

    1. 1docker info fails in the same terminal or IDE session that runs the testsDocker is not running, or the test shell cannot reach itFix
    2. 2You use Podman or Colima and docker-machine is the last errorAn alternative runtime such as Podman or Colima is not configuredFix
    3. 3DOCKER_HOST is set in your profile to a daemon that is goneDOCKER_HOST or the TLS variables point at nothingFix

What does the error look like?

  • docker-machine executable was not found on PATH

Cause 1 of 3

Docker is not running, or the test shell cannot reach it

1Check

Docker on Linux and Docker Desktop on Mac and Windows are detected automatically, so a failure usually means the daemon is not running.

docker info
systemctl is-active docker

2Fix

Start the daemon (or Docker Desktop) and run the tests again from the same shell.

sudo systemctl start docker

3Verify

docker info prints server details, then the tests start containers.

docker info

Confirmed by java.testcontainers.org

Did this fix it?

Cause 2 of 3

An alternative runtime such as Podman or Colima is not configured

1Check

Other runtimes may need manual setup: Testcontainers reads DOCKER_HOST first, and some runtimes need extra variables.

echo "$DOCKER_HOST"; ls ${XDG_RUNTIME_DIR}/podman/podman.sock

2Fix

Point DOCKER_HOST at the runtime's socket. For Podman on Linux that is the podman socket, and for rootless mode also disable Ryuk.

export DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock
export TESTCONTAINERS_RYUK_DISABLED=true   # rootless Podman only

3Verify

Run one container test and watch it start.

docker info

Confirmed by java.testcontainers.org

Did this fix it?

Cause 3 of 3

DOCKER_HOST or the TLS variables point at nothing

1Check

Environment variables are strategy number one: DOCKER_HOST, DOCKER_TLS_VERIFY and DOCKER_CERT_PATH. If the daemon is not there, the later strategies run.

env | grep -E "^DOCKER_"

2Fix

Unset the stale variables, or set DOCKER_HOST to the daemon that is really running.

unset DOCKER_HOST DOCKER_TLS_VERIFY DOCKER_CERT_PATH

3Verify

Re-run the tests in a fresh shell.

env | grep -E "^DOCKER_"

Confirmed by java.testcontainers.org

Did this fix it?

How do I stop it coming back?

  • Start the container runtime before the build, and have CI run docker info as its first step.
  • Set DOCKER_HOST once per machine or CI image, not per test run.
  • Keep Docker Machine out of the picture: it is only the last fallback Testcontainers tries.

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.