Testcontainers "host.docker.internal" not resolving in CI

Containers that expect to reach the host via host.docker.internal may fail on Linux CI, where that name is not automatically mapped. The container gets a resolution error instead of the host address.

What this error means

A container cannot connect to a service on the runner host and logs a DNS failure for host.docker.internal, even though the same setup works on Docker Desktop locally.

Testcontainers

Could not resolve host: host.docker.internal
(the name is not mapped by default on Linux Docker engines)

Common causes

Linux Docker does not map the name by default

Docker Desktop provides host.docker.internal, but a plain Linux engine on CI does not, so the name fails to resolve inside containers.

The container hardcodes the host name

Code that assumes host.docker.internal works everywhere breaks on runners where it is not configured.

How to fix it

Expose the host to containers via Testcontainers

Use the Testcontainers host access helper, which sets up the internal host mapping for the containers it starts.

Java

org.testcontainers.Testcontainers.exposeHostPorts(8080);
// containers then reach the host at "host.testcontainers.internal:8080"

Add the host-gateway mapping when running raw containers

For containers not managed by the helper, add an explicit host mapping so the name resolves on Linux.

Terminal

docker run --add-host=host.docker.internal:host-gateway ...

How to prevent it

Use the Testcontainers host access helper rather than hardcoding host names.
Add host-gateway mappings explicitly when running raw containers on Linux.
Do not assume Docker Desktop conveniences exist on Linux CI.