host.docker.internal on Linux: Why It Fails and the 1-Line Fix (2026)
· 5 min read
host.docker.internal does not exist on Linux by default — Docker only creates it automatically on macOS and Windows. On Docker 20.10 and newer you opt in with one line: extra_hosts: - "host.docker.internal:host-gateway". That maps the name to the Docker bridge gateway, so your container can reach services running on the host.
If you've moved a Docker project from a Mac to a Linux server, this is the error you hit:
Connection refused: host.docker.internal:3000
On macOS and Windows, host.docker.internal is a magic DNS name that resolves to your host machine's IP address. It's incredibly useful for connecting containers to local databases or APIs running outside of Docker.
But on Linux? It doesn't exist by default.