Testcontainers (Java) fails with 'docker-machine executable was not found on PATH'
docker-machine executable was not found on PATHShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
docker info fails in the same terminal or IDE session that runs the testsDocker is not running, or the test shell cannot reach itFix - 2
You use Podman or Colima and docker-machine is the last errorAn alternative runtime such as Podman or Colima is not configuredFix - 3
DOCKER_HOST is set in your profile to a daemon that is goneDOCKER_HOST or the TLS variables point at nothingFix
- 1
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 docker2Fix
Start the daemon (or Docker Desktop) and run the tests again from the same shell.
sudo systemctl start docker3Verify
docker info prints server details, then the tests start containers.
docker infoConfirmed by java.testcontainers.org
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.sock2Fix
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 only3Verify
Run one container test and watch it start.
docker infoConfirmed by java.testcontainers.org
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_PATH3Verify
Re-run the tests in a fresh shell.
env | grep -E "^DOCKER_"Confirmed by java.testcontainers.org
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
Servers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 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
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix