PostgreSQLIntermediateHigh severity
PostgreSQL connection refused
The client reached the host but no PostgreSQL server accepted the connection on that port.
10-30 min Popularity 88/100 Verified 2026-07-21
What does this error mean?
The network connection was rejected before authentication, usually because PostgreSQL is stopped, listening elsewhere, or unreachable from the current container or host.
Why does this happen?
- The PostgreSQL service is stopped.
- The host or port is incorrect.
- A container is using localhost to refer to itself instead of the database service.
- PostgreSQL is not listening on the required interface.
- A firewall or network policy blocks the port.
AI explanation
Plain-English analysis
This is a transport failure, not a bad password. The application could not establish a TCP connection to PostgreSQL, so database authentication never began.
Quick fix
Terminal
pg_isready -h localhost -p 5432 psql "$DATABASE_URL"
Expected output: The server reports that it is accepting connections.
Step-by-step fix
1Start PostgreSQL and verify the portCheck the service status and confirm which address and port it is listening on.77%
2Use the Docker service nameInside Compose, connect to `db:5432` rather than `localhost:5432`.64%
3Correct the connection URLVerify protocol, host, port, database, and SSL settings.45%
Alternative solutions
Docker Compose
DATABASE_URL=postgresql://user:pass@db:5432/app
Use the database service name on the Compose network.
Linux
sudo systemctl status postgresql ss -ltnp | grep 5432
Confirm the process is listening.
Supabase
Use the project connection string and required SSL mode.
Use the pooler connection for serverless workloads when appropriate.
Real example
Broken
dotenv
DATABASE_URL=postgresql://app:secret@localhost:5432/app # inside web container
Corrected
dotenv
DATABASE_URL=postgresql://app:secret@db:5432/app # Compose service name
Frequently asked questions
Usually no. A wrong password produces an authentication error after the server accepts the connection.