connect: connection refused

Common causes

• The target service (database, API, another container) isn't running or isn't ready yet
• Connecting to localhost inside a container when the service is in another container — use the service name instead
• The target container is on a different Docker network and can't be reached
• The service is running but on a different port than what's configured in the app

How to fix it

1. In Docker Compose, use the service name as the hostname: db instead of localhost for a database container
2. Add a health check and depends_on to wait for the service to be ready before connecting
3. Verify all containers are on the same network: docker network inspect NETWORK_NAME
4. Check the target service is actually listening on the expected port: docker exec service-container ss -tlnp

Example

App container tries to connect to localhost:5432, but the database is in a separate container — use the service name 'db' instead