How to fix Could not resolve host: api.example.com in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 173 views

The 'Could not resolve host' error occurs when Docker containers cannot perform DNS lookups to translate hostnames into IP addresses. This is commonly caused by misconfigured DNS settings, systemd-resolved conflicts on Linux, or network isolation issues.

Quick fix

Fixes Could not resolve host: api.example.com

docker run --rm alpine cat /etc/resolv.conf
  1. Check container DNS configuration
  2. Check host DNS configuration
  3. Fix systemd-resolved symlink (Ubuntu 18.04+)
  4. Configure Docker daemon with explicit DNS
docker — error
docker run --rm alpine cat /etc/resolv.conf
Could not resolve host: api.example.com

What this error means

When you see "Could not resolve host" in Docker, it means your container's DNS resolver cannot translate a hostname (like api.example.com or registry.npmjs.org) into an IP address. This prevents the container from establishing network connections to external services. Docker handles DNS by copying the host's /etc/resolv.conf into containers, filtering out localhost nameservers (like 127.0.0.1 or 127.0.0.53). If no valid nameservers remain after filtering, Docker falls back to Google's public DNS servers (8.8.8.8 and 8.8.4.4). The problem often occurs on Ubuntu 18.04+ and other systems using systemd-resolved, which uses 127.0.0.53 as a local DNS cache. Since containers cannot reach the host's localhost, they lose access to DNS resolution entirely.

Typical symptoms

  • Docker build fails with 'Could not resolve host' during package installation
  • Container cannot reach external APIs or services
  • curl, wget, or apt-get commands fail inside containers
  • npm install or pip install fails with network/DNS errors
  • Works fine on host machine but fails inside container
  • docker exec ping google.com returns 'Name or service not known'

Common causes

  1. Host uses systemd-resolved with 127.0.0.53 which containers cannot reach
  2. Host's /etc/resolv.conf contains only localhost nameservers (127.0.0.1, 127.0.0.53)
  3. Corporate firewall blocking Google DNS (8.8.8.8) that Docker falls back to
  4. Docker daemon not configured with accessible DNS servers
  5. NetworkManager or dnsmasq using localhost DNS that containers cannot access
  6. Firewall rules blocking DNS traffic from Docker bridge network
  7. VPN software interfering with container DNS resolution

How to fix "Could not resolve host: api.example.com"

1Check container DNS configuration

First, verify what DNS servers your container is using:

bash
docker run --rm alpine cat /etc/resolv.conf

If you see nameserver 127.0.0.11 (Docker's embedded DNS) or valid external IPs, the issue may be elsewhere. If you see no nameservers or only localhost addresses, proceed with the fixes below.

2Check host DNS configuration

Examine your host's DNS settings:

bash
cat /etc/resolv.conf

If you see nameserver 127.0.0.53 (systemd-resolved) or nameserver 127.0.0.1 (dnsmasq), this is likely the cause. Docker filters these out, leaving containers without valid DNS.

3Fix systemd-resolved symlink (Ubuntu 18.04+)

On systems using systemd-resolved, change the resolv.conf symlink to point to the file with real DNS servers:

bash
sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf

Then restart Docker:

bash
sudo systemctl restart docker

This exposes the actual upstream DNS servers to Docker instead of the local stub resolver.

4Configure Docker daemon with explicit DNS

Create or edit /etc/docker/daemon.json to specify DNS servers:

bash
sudo nano /etc/docker/daemon.json

Add the following (adjust DNS servers as needed for your network):

json
{
  "dns": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
}

Restart Docker to apply:

bash
sudo systemctl restart docker

Note: If you're behind a corporate firewall, use your internal DNS servers instead of public ones.

5Use --dns flag for individual containers

For a quick fix or testing, specify DNS directly when running containers:

bash
docker run --dns 8.8.8.8 --dns 8.8.4.4 your-image

For Docker Compose, add to your service:

yaml
services:
  your-service:
    image: your-image
    dns:
      - 8.8.8.8
      - 8.8.4.4
6Use host network mode (workaround)

As a workaround, you can use the host's network stack directly:

bash
docker run --network host your-image

Or in Docker Compose:

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

Warning: This removes network isolation between container and host, which may not be suitable for production or multi-container setups.

7Check firewall rules

Ensure your firewall allows DNS traffic from Docker's bridge network:

bash
# For firewalld
sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
sudo firewall-cmd --reload

# For ufw
sudo ufw allow in on docker0

Also verify that outbound UDP port 53 is not blocked for Docker containers.

Advanced notes

User-defined networks: Docker's embedded DNS server (127.0.0.11) only works in user-defined bridge networks, not the default bridge. If you create a custom network with docker network create mynet and attach containers to it, they can resolve each other by container name and benefit from better DNS handling.

Docker Desktop vs. Docker Engine: Docker Desktop on macOS and Windows handles DNS differently through its VM layer. These instructions primarily apply to Docker Engine on Linux.

Kubernetes considerations: If running Docker containers within Kubernetes, DNS is handled by CoreDNS/kube-dns. Container-level DNS settings may be overridden by pod specs.

VPN interference: Some VPN clients (especially corporate VPNs) modify the host's routing and DNS in ways that break Docker networking. Try disconnecting the VPN to test, or configure the VPN to exclude Docker's subnet (typically 172.17.0.0/16).

Rootless Docker: In rootless mode, networking behaves differently. You may need to use slirp4netns with custom DNS settings or configure the user's network namespace.

Frequently asked questions

What does "Could not resolve host: api.example.com" mean?
org) into an IP address. This prevents the container from establishing network connections to external services. 53).
How do I fix "Could not resolve host: api.example.com"?
The 'Could not resolve host' error occurs when Docker containers cannot perform DNS lookups to translate hostnames into IP addresses. This is commonly caused by misconfigured DNS settings, systemd-resolved conflicts on Linux, or network isolation issues.
What causes "Could not resolve host: api.example.com"?
Host uses systemd-resolved with 127.0.0.53 which containers cannot reach Host's /etc/resolv.conf contains only localhost nameservers (127.0.0.1, 127.0.0.53) Corporate firewall blocking Google DNS (8.8.8.8) that Docker falls back to
Is the "Could not resolve host: api.example.com" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading