Testcontainers for Node.js cannot find a container runtime in Jest
Could not find a working container runtime strategyShort answer
Testcontainers could not reach a container engine from the test process. Start Docker, then run once with DEBUG=testcontainers* to see why. If you use Podman, Colima or Rancher Desktop, set DOCKER_HOST to that engine's socket and TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE to /var/run/docker.sock.
Fix it fast
1Find out which cause you have
Run the tests with Testcontainers logging on. It prints which strategy was tried and why it failed.
DEBUG=testcontainers* npx jest2Match what you see, then jump to its fix
- 1
The debug log shows DOCKER_HOST being used and a connection errorDOCKER_HOST points at an engine that is not answeringFix - 2
You run Podman, not Docker, and DOCKER_HOST is emptyPodman is used and its socket is not enabled or exportedFix - 3
Docker Desktop is not installed and /var/run/docker.sock does not existColima or Rancher Desktop keeps its socket outside the default pathFix - 4
Tests run in CI or inside a container and the daemon is a separate serviceThe engine runs on another host, such as a Docker-in-Docker serviceFix
- 1
What does the error look like?
Could not find a working container runtime strategy
Cause 1 of 4
DOCKER_HOST points at an engine that is not answering
1Check
The Testcontainers configuration docs describe DOCKER_HOST as the URL of the Docker daemon.
echo $DOCKER_HOST
docker info2Fix
Unset it, or set it to an endpoint that answers, then run the tests again.
unset DOCKER_HOST
docker info3Verify
docker info prints server details, and the tests start containers.
npx jestConfirmed by raw.githubusercontent.com
Cause 2 of 4
Podman is used and its socket is not enabled or exported
1Check
The supported-runtimes docs say Podman needs its socket enabled on Linux (rootless or rootful) and DOCKER_HOST exported from the path that podman info reports.
podman info --format '{{.Host.RemoteSocket.Path}}'2Fix
On Linux, make sure the rootless socket is active (the docs check it with systemctl --user status) and export the path. On macOS, take the path from podman machine inspect. When rootless, the docs say to disable the resource reaper.
systemctl --user status podman.socket
export DOCKER_HOST=unix://$(podman info --format '{{.Host.RemoteSocket.Path}}')
export TESTCONTAINERS_RYUK_DISABLED=true3Verify
Run the test suite from the same shell.
npx jestConfirmed by raw.githubusercontent.com
Cause 3 of 4
Colima or Rancher Desktop keeps its socket outside the default path
1Check
The docs list the socket location for each tool. Colima uses ~/.colima/default/docker.sock and Rancher Desktop uses ~/.rd/docker.sock.
ls -l ~/.colima/default/docker.sock ~/.rd/docker.sock2Fix
Export DOCKER_HOST for the tool you use, and the override for the socket path inside containers.
# Colima
export DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock3Verify
Run one container test.
npx jestConfirmed by raw.githubusercontent.com
Cause 4 of 4
The engine runs on another host, such as a Docker-in-Docker service
1Check
The configuration docs give tcp://docker:2375 as an example DOCKER_HOST, and list DOCKER_TLS_VERIFY and DOCKER_CERT_PATH for TLS. TESTCONTAINERS_HOST_OVERRIDE sets the host on which ports are exposed.
env | grep -i docker2Fix
Set DOCKER_HOST to the daemon service address in the test job.
export DOCKER_HOST=tcp://docker:23753Verify
The job starts a container and reaches it.
DEBUG=testcontainers* npx jestConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Document the DOCKER_HOST setup for every runtime your team uses in the README.
- Add a setup step that runs docker info and fails with a clear message.
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
Back end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix