Error: ECONNREFUSED

ECONNREFUSED in Docker environments has a distinct cause that differs from bare-metal connections. When two containers need to communicate — a Node.js app connecting to PostgreSQL, Redis, or another service — localhost inside a container refers to the container itself, not the host machine. A Node.js app connecting to localhost:5432 inside Docker will always get ECONNREFUSED if PostgreSQL is in a different container. The correct approach in Docker Compose is to use the service name as the hostname: if your docker-compose.yml defines a service named db, connect to db:5432. Docker Compose creates an internal DNS resolver that maps service names to their container IPs. This only works when both containers are on the same Docker network — explicitly defining a shared networks block in your Compose file ensures this. For Node.js apps connecting to services on the Docker host machine (the laptop or server running Docker), use host.docker.internal (works on Docker Desktop for Mac/Windows automatically) or the gateway IP (172.17.0.1 on the default Linux Docker bridge network). This distinction — container-to-container versus container-to-host — accounts for most ECONNREFUSED errors in containerized development, and the fix is always in the connection string, not the application code.