Postgres "could not translate host name 'postgres'" in CI

The client tried to resolve a hostname like postgres and DNS returned "Name or service not known". The service-container network name is not resolvable from where your step runs - a networking/topology issue, occasionally a transient resolver hiccup.

What this error means

psql/migrate fails with "could not translate host name to address: Name or service not known". It commonly appears when a step running directly on the runner (not in a container) uses the service name instead of localhost.

psql: error: could not translate host name "postgres" to address:
Name or service not known

Common causes

Service name used from a non-container step

On GitHub Actions, service hostnames like postgres resolve only inside container jobs. Steps running directly on the runner must use localhost with the mapped port.

Service alias not on this network

The container is on a different network or under a different alias than the name in the connection string.

Transient DNS resolution hiccup

A brief resolver delay or flake can intermittently fail to resolve an otherwise-valid name.

How to fix it

Use localhost + mapped port for runner steps

Map the service port and connect via localhost when your job is not containerized.

services:
  postgres:
    image: postgres:16
    ports: ['5432:5432']
    env: { POSTGRES_PASSWORD: postgres }
env:
  DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app

Or run the job in a container

1. Add container: to the job so it joins the service network.
2. Then the service name (e.g. postgres) resolves correctly.
3. Pick one model consistently; do not mix localhost and service names.

How to prevent it

• Decide container-job vs runner-step early and choose the host accordingly.
• Map ports when connecting from the runner host.
• On managed runners (Latchkey), self-healing auto-retries transient failures like a momentary DNS resolution flake.

Related guides