Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

A container cannot resolve the name of its database container

Errordial tcp: lookup db on 127.0.0.11:53: no such host

Short answer

127.0.0.11 is Docker's own DNS server for custom networks. Its answer, no such host, means that no container on this network answers to that name. The name is wrong, the two containers sit on different networks or on the default bridge, or the app asked before the database container started.

  • Applies to Docker Engine 28, Docker Compose 2, Go 1.23, PHP 8.3 (Adminer)
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Resolve the name from inside the failing container, then list the names Compose knows. The first command shows whether Docker's DNS knows the name at all.

    docker compose exec app getent hosts db
    docker compose config --services
  2. 2Match what you see, then jump to its fix

    1. 1getent prints nothing, and the host in the connection string is not in the list of servicesThe host name is not the name of a service or containerFix
    2. 2The name is right, but the app was started with docker run, or the compose file lists different networks per serviceThe containers are not on the same user-defined networkFix
    3. 3The error appears once, right after docker compose up, and a manual restart of the app makes it disappearThe app starts and asks for the database before it is upFix

What does the error look like?

  • dial tcp: lookup db on 127.0.0.11:53: no such host
  • php_network_getaddresses: getaddrinfo failed

Cause 1 of 3

The host name is not the name of a service or container

1Check

Each Compose service registers its own name with an internal DNS server, and that is the name other containers use. A host written as localhost, as an old container name, or as a name from another project does not match. In Adminer, the Server field of the login form needs the same name.

docker compose config --services
grep -n -E "DB_HOST|DATABASE_URL|host=" .env compose.yaml

2Fix

Write the service name exactly as it appears under services: in the compose file. If you must keep another name, give the service a network alias.

services:
  db:
    image: postgres:17
    networks:
      default:
        aliases: [database]
  app:
    build: .
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/appdb

3Verify

The name now resolves from the app container.

docker compose exec app getent hosts db

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The containers are not on the same user-defined network

1Check

Automatic name resolution belongs to user-defined networks. On the default bridge, containers can reach each other only by IP address. Compose creates a network for the project, but a container started by hand with docker run lands on the default bridge unless you say otherwise.

docker inspect --format '{{json .NetworkSettings.Networks}}' <app-container>
docker inspect --format '{{json .NetworkSettings.Networks}}' <db-container>

2Fix

Attach both to one network. For a container started by hand, name the project's network.

docker network ls
docker run --rm --network myproject_default my-go-app

3Verify

From the app container the name resolves and the port answers.

docker run --rm --network myproject_default busybox nslookup db

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The app starts and asks for the database before it is up

1Check

Compose starts containers in dependency order, which comes from depends_on and similar settings. Even then it waits only until a container is running, not until the database is ready. A program that gives up on its first failed lookup or connection then exits.

docker compose logs db --tail 30

2Fix

Declare the dependency with a health check on the database, so the app container is created only when the database reports healthy. For Postgres the documented check is pg_isready. Let the app retry its connection too.

services:
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s

3Verify

docker compose up shows db as healthy before the app starts, and the error is gone.

docker compose ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep every host name for another container in one place, such as an environment variable in the compose file, so a rename needs one change.
  • Start helper containers like Adminer from the same compose file as the database, so they share its network.
  • Give each database a health check and depend on it with condition: service_healthy.
  • When a message names 127.0.0.11, read it as the question is reaching Docker's DNS; the problem is then the name or the network, not the host machine's DNS.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

Docker pull or container DNS fails with "server misbehaving"

docker pull fails while a browser on the same machine opens the registry fine

'Server misbehaving' is a Go resolver error: the DNS server answered, but with a reply code that is neither success nor name-not-found.

3 causes, each with a fix

Back end

PHP cannot turn a hostname into an IP address

Warning: file_get_contents(): php_network_getaddresses: getaddrinfo failed

This warning means the operating system could not resolve the hostname PHP was asked to connect to.

3 causes, each with a fix

Databases

PHP throws "could not find driver" when it opens a PDO connection

Fatal error: Uncaught PDOException: could not find driver in /var/www/app/db.php:12

PDO is only a layer; each database needs its own driver extension, such as pdo_mysql or pdo_pgsql, and the DSN prefix must name a driver that is loaded.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.