Redis "Name or service not known" service hostname in CI

DNS resolution for the Redis host failed: "Name or service not known" (EAI_NONAME) means the name redis does not exist on the network the client is using. Service names only resolve for jobs on the same Docker network as the service, not for jobs on the runner host.

What this error means

A step fails with "Could not connect to Redis at redis:6379: Name or service not known" or the Node error "getaddrinfo ENOTFOUND redis" when connecting by service name.

Could not connect to Redis at redis:6379: Name or service not known
# node client:
Error: getaddrinfo ENOTFOUND redis

Common causes

Runner-host job using the container network name

A job that runs directly on the runner cannot resolve the service alias redis; it must use localhost and the port published with ports:.

Container job that never joined the service network

A container job resolves service names, but only if the service is declared for that job; a compose-only service is not visible to a plain services: job.

How to fix it

Use the host that matches the job model

1. For a job on the runner host: use localhost and the mapped port.
2. For a container: job: use the service name redis and the internal port 6379.
3. Never mix the two host schemes in one job.

# runner-host job
services:
  redis:
    image: redis:7
    ports: ['6379:6379']   # connect via localhost:6379

Connect by service name on a container job

When the job itself runs in a container, the service is reachable by its label on the Docker network at its internal port.

container: node:20
services:
  redis:
    image: redis:7   # connect via redis://redis:6379

How to prevent it

• Decide the job model (runner host vs container) and pick the host accordingly.
• Publish ports: for runner-host jobs; rely on service names only in container jobs.
• Keep the host in an env var so it is easy to switch per workflow.

Related guides