How to fix dial tcp: lookup host.docker.internal: no such host in Docker

What this error means

When Docker containers need to communicate with services running on the host machine, they use the special DNS name `host.docker.internal`. This hostname is designed to resolve to an IP address that allows containers to reach the host network. On Docker Desktop for macOS and Windows, `host.docker.internal` is automatically configured and resolves correctly. However, on Linux systems running Docker Engine (not Docker Desktop), this DNS name is not available by default. The container's DNS resolver cannot find the hostname, resulting in the "no such host" error. This is a common source of confusion when developing locally with Docker. Code that works perfectly on macOS or Windows will fail on Linux CI/CD systems or production servers because the `host.docker.internal` resolution is not automatic. The solution involves explicitly mapping this hostname to the host's gateway IP address.

Typical symptoms

• Container fails to connect to services running on the Docker host
• Error message contains 'lookup host.docker.internal: no such host'
• Application works on macOS/Windows but fails on Linux
• Connection to localhost from within container fails
• CI/CD pipeline fails when container tries to reach host services
• Database connections using host.docker.internal time out or fail
• API calls from container to host machine services return DNS errors

Common causes

1. Running Docker Engine on Linux without explicit host.docker.internal configuration (most common)
2. Docker version older than 20.10 which lacks host-gateway support
3. Missing extra_hosts configuration in docker-compose.yml
4. Missing --add-host flag when using docker run
5. Docker Desktop for Linux not configured to enable host.docker.internal
6. Custom DNS configuration in Docker daemon overriding default resolution
7. Network mode incompatibility preventing host gateway access
8. Firewall blocking connections from container to host network

How to fix "dial tcp: lookup host.docker.internal: no such host"

services:
  your-service:
    image: your-image
    extra_hosts:
      - "host.docker.internal:host-gateway"

services:
  app:
    image: node:18
    extra_hosts:
      - "host.docker.internal:host-gateway"

  worker:
    image: python:3.11
    extra_hosts:
      - "host.docker.internal:host-gateway"

docker compose down
docker compose up -d

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

docker run -d \
  --name my-app \
  --add-host=host.docker.internal:host-gateway \
  -p 3000:3000 \
  my-app-image

docker exec my-app cat /etc/hosts

172.17.0.1    host.docker.internal

docker --version

# Remove old version
sudo apt remove docker docker-engine docker.io containerd runc

# Install latest Docker
curl -fsSL https://get.docker.com | sudo sh

# Verify version
docker --version

sudo yum remove docker docker-common docker-selinux docker-engine
curl -fsSL https://get.docker.com | sudo sh
docker --version

# Download the .deb package from Docker's website
# https://docs.docker.com/desktop/install/ubuntu/

sudo apt install ./docker-desktop-<version>-amd64.deb

services:
  your-service:
    image: your-image
    network_mode: host

docker run --network host your-image

docker network inspect bridge --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'

services:
  your-service:
    image: your-image
    extra_hosts:
      - "host.docker.internal:172.17.0.1"

docker run --add-host=host.docker.internal:172.17.0.1 your-image

# Allow from Docker bridge subnet
sudo ufw allow from 172.17.0.0/16

# Or more specifically, allow a port
sudo ufw allow from 172.17.0.0/16 to any port 5432

# Add Docker zone
sudo firewall-cmd --permanent --zone=docker --add-source=172.17.0.0/16
sudo firewall-cmd --permanent --zone=docker --add-port=5432/tcp
sudo firewall-cmd --reload

docker run --rm --add-host=host.docker.internal:host-gateway alpine \
  sh -c "apk add --no-cache curl && curl -v host.docker.internal:5432"

# This only accepts local connections
postgres -h 127.0.0.1 -p 5432

# This accepts connections from any interface
postgres -h 0.0.0.0 -p 5432

# Or bind to the Docker bridge specifically
postgres -h 172.17.0.1 -p 5432

listen_addresses = '*'

bind-address = 0.0.0.0

// Instead of
app.listen(3000, '127.0.0.1');
// Use
app.listen(3000, '0.0.0.0');

Advanced notes

services:
  app:
    environment:
      - DB_HOST=host.docker.internal
    extra_hosts:
      - "host.docker.internal:host-gateway"

# Check if hostname resolves
docker run --rm --add-host=host.docker.internal:host-gateway alpine nslookup host.docker.internal

# Check /etc/hosts entry
docker run --rm --add-host=host.docker.internal:host-gateway alpine cat /etc/hosts

# Test TCP connectivity
docker run --rm --add-host=host.docker.internal:host-gateway alpine nc -zv host.docker.internal 5432

services:
  app:
    depends_on:
      - db
    environment:
      - DB_HOST=db  # Use service name instead
  db:
    image: postgres

Frequently asked questions

What does "dial tcp: lookup host.docker.internal: no such host" mean?

internal. This hostname is designed to resolve to an IP address that allows containers to reach the host network. internal is automatically configured and resolves correctly.

How do I fix "dial tcp: lookup host.docker.internal: no such host"?

This error occurs when a container tries to connect to host.docker.internal but the DNS name is not configured. On Linux, host.docker.internal requires explicit configuration unlike macOS and Windows where it works automatically.

What causes "dial tcp: lookup host.docker.internal: no such host"?

Running Docker Engine on Linux without explicit host.docker.internal configuration (most common) Docker version older than 20.10 which lacks host-gateway support Missing extra_hosts configuration in docker-compose.yml

Is the "dial tcp: lookup host.docker.internal: no such host" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• dial tcp: connect: no route to host

  How to fix 'no route to host' in Docker

  MEDIUM

• Error response from daemon: operation not permitted (no-new-privileges)

  How to fix 'operation not permitted (no-new-privileges)' in Docker

  MEDIUM

• write /var/lib/docker/tmp/...: no space left on device

  How to fix 'no space left on device' during Docker build

  MEDIUM

• Error response from daemon: no matching manifest for linux/arm64 in the manifest list entries

  How to fix 'no matching manifest for linux/arm64' in Docker

  MEDIUM

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Desktop Networking - Docker Docs(Official Docs)
• 📖
  Docker Compose Services - extra_hosts - Docker Docs(Official Docs)
• 📖
  Docker Engine Networking - Docker Docs(Official Docs)
• 📝
  How Docker Desktop Networking Works Under the Hood - Docker Blog
• 💬
  What is the Linux equivalent of host.docker.internal? - Stack Overflow(Stack Overflow)
• 💬
  lookup host.docker.internal: no such host - Stack Overflow(Stack Overflow)
• 💬
  host.docker.internal missing in Linux (Ubuntu) - Docker Forums(Stack Overflow)
• 📝
  How to connect to the Docker host from inside a Docker container - Medium
• 📝
  The Equivalent of --add-host in Docker Compose - Baeldung
• 🐙
  Support host.docker.internal DNS name to host - GitHub Issue(GitHub)