Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Testcontainers for Node.js cannot find a container runtime in Jest

ErrorCould not find a working container runtime strategy

Short 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.

  • Applies to testcontainers for Node.js, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 jest
  2. 2Match what you see, then jump to its fix

    1. 1The debug log shows DOCKER_HOST being used and a connection errorDOCKER_HOST points at an engine that is not answeringFix
    2. 2You run Podman, not Docker, and DOCKER_HOST is emptyPodman is used and its socket is not enabled or exportedFix
    3. 3Docker Desktop is not installed and /var/run/docker.sock does not existColima or Rancher Desktop keeps its socket outside the default pathFix
    4. 4Tests 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

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 info

2Fix

Unset it, or set it to an endpoint that answers, then run the tests again.

unset DOCKER_HOST
docker info

3Verify

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

npx jest

Confirmed by raw.githubusercontent.com

Did this fix it?

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=true

3Verify

Run the test suite from the same shell.

npx jest

Confirmed by raw.githubusercontent.com

Did this fix it?

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.sock

2Fix

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.sock

3Verify

Run one container test.

npx jest

Confirmed by raw.githubusercontent.com

Did this fix it?

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 docker

2Fix

Set DOCKER_HOST to the daemon service address in the test job.

export DOCKER_HOST=tcp://docker:2375

3Verify

The job starts a container and reaches it.

DEBUG=testcontainers* npx jest

Confirmed by raw.githubusercontent.com

Did this fix it?

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 fix

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.