Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

NestJS cannot resolve the host name redis when using Docker Compose

ErrorError: getaddrinfo ENOTFOUND redis

Short answer

The name redis only exists inside the Compose network, as the service name. The error means the process looking it up is outside that network, uses a different name, or sits on another network. Run the app as a Compose service, copy the service name exactly into the host setting, and put both services on one network.

  • Applies to Docker Compose 2.x, NestJS 11, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Docker's DNS from inside the app container. If the name resolves here, the problem is where your app runs; if it fails, it is the name or the network.

    docker compose ps
    docker compose exec api getent hosts redis
  2. 2Match what you see, then jump to its fix

    1. 1You start Nest with npm run start:dev on your laptop and only Redis is in ComposeThe Nest app runs on the host, not inside ComposeFix
    2. 2getent hosts redis prints nothing while docker compose ps lists the cache under another nameThe host name does not match the Compose service nameFix
    3. 3Both containers run, the name is right, and the lookup still failsThe app and Redis are on different networksFix

What does the error look like?

  • Error: getaddrinfo ENOTFOUND redis
  • code: 'ENOTFOUND'

Cause 1 of 3

The Nest app runs on the host, not inside Compose

1Check

Compose registers service names with an internal DNS server for containers. A process on the host does not use that DNS, so redis does not resolve there.

node -e "require('dns').lookup('redis', e => console.log(e && e.code))"

2Fix

Publish the Redis port in Compose and point the host-run app at localhost. Keep the name redis only for code that runs in a container.

# compose.yaml
services:
  redis:
    image: redis:7
    ports:
      - "6379:6379"

# .env for a host-run app
REDIS_HOST=localhost

3Verify

Restart the app and ping Redis through the published port.

docker compose up -d redis
docker compose exec redis redis-cli ping

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The host name does not match the Compose service name

1Check

Containers are discoverable by the service name (the key under services). A renamed service, a typo, or a value copied from another project breaks the lookup.

docker compose config --services
docker compose exec api printenv | grep -i redis

2Fix

Make the host setting equal to the service key, or give the service an extra name with a network alias.

services:
  cache:
    image: redis:7
    networks:
      default:
        aliases:
          - redis

3Verify

Resolve the name from inside the app container again.

docker compose exec api getent hosts redis

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The app and Redis are on different networks

1Check

Services can only reach each other if they share a network. When any service lists its own networks, it no longer joins the default one unless you say so.

docker compose config | grep -n -B1 -A4 "networks"

2Fix

Attach both services to at least one common network.

services:
  api:
    networks: [backend]
  redis:
    image: redis:7
    networks: [backend]
networks:
  backend: {}

3Verify

Recreate the stack and look the name up from the app container.

docker compose up -d --force-recreate
docker compose exec api getent hosts redis

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Read the Redis host from an environment variable with separate values for host-run and container-run apps.
  • Name services once and reuse that exact name in every config file.
  • Use one explicit network when you give any service a networks list.

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

You edit NestJS code but the container keeps running the old version

nest start --watch prints nothing after a file is saved

Hot reload in a container needs three things: the dev stage of your Dockerfile must be the one that runs, your edited files must reach the container, and the container must run a watch command.

3 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.