Testcontainers Docker-in-Docker vs mounted socket confusion in CI

By Daniel Zoghalchali·Latchkey

Testcontainers containers start but your test cannot reach them, because the job assumes one Docker model while the runner provides another. With a mounted host socket, containers are siblings on the host; with true Docker-in-Docker they live inside a nested daemon. Getting the two confused breaks host and port resolution.

What this error means

Containers start (visible in logs) but the test connection to the mapped host/port times out. Switching between a mounted socket and a real DinD daemon changes whether localhost or an internal host reaches the container.

Testcontainers

Container is running, but the test connection to localhost:<mapped-port> refuses or times out.
(With a mounted host socket, "localhost" from a job container is not the host where the container published its port.)

Common causes

Mounted socket makes containers siblings, not children

When you mount /var/run/docker.sock, Testcontainers starts containers on the host daemon. From inside a job container, localhost is not the host, so a published port is not at localhost.

True DinD runs a separate nested daemon

A docker:dind service runs its own daemon; your client must point DOCKER_HOST at it, and container reachability follows that daemon, not the host.

How to fix it

Prefer running on the runner host, not a job container

Running Testcontainers directly on ubuntu-latest avoids the sibling-container host confusion entirely, since the test process and the containers share the same host.

.github/workflows/ci.yml

jobs:
  test:
    runs-on: ubuntu-latest   # test process and containers share one host

If using DinD, point the client at the DinD daemon

With a true DinD service, set DOCKER_HOST to the DinD address and use the Testcontainers host helper instead of assuming localhost.

.github/workflows/ci.yml

env:
  DOCKER_HOST: tcp://docker:2375

How to prevent it

Pick one model (host socket or DinD) and keep the whole job consistent with it.
Use the Testcontainers host helper rather than hardcoding localhost.
Run tests on the runner host where possible to sidestep nested networking.

Frequently asked questions

What causes "DinD vs docker.sock mount"?

When you mount /var/run/docker.sock, Testcontainers starts containers on the host daemon. From inside a job container, localhost is not the host, so a published port is not at localhost.

How do I fix DinD vs docker.sock mount?

Running Testcontainers directly on ubuntu-latest avoids the sibling-container host confusion entirely, since the test process and the containers share the same host.