Connection Refused
Error message
Connection refused
Quick summary
The database server is not running, not listening on the expected port, or not accepting connections from your host.
Why this happens
The database server is not running
The server is listening on a different port than configured
A firewall is blocking the connection
The host address is wrong (e.g., localhost vs a remote server)
The server has reached its max_connections limit
Minimal example
# Connecting to a server that is not running
psql -h localhost -p 5432 -U postgres
# → connection refused# Start the server first, then connect
pg_ctl start
psql -h localhost -p 5432 -U postgresThe server was not running. Starting it first allows the connection to succeed.
How to diagnose
Check if the database service is running:
pg_isreadyfor PostgreSQL ormysqladmin pingfor MySQLVerify the host and port in your connection string
Check firewall rules and network connectivity
Check the server's max_connections and current connection count
How to fix
Start the database server
Update your connection string with the correct host and port
Open the required port in the firewall
Increase max_connections or close idle connections
How to prevent
Use connection pooling with health checks
Monitor database server uptime and alert on downtime
Keep connection configuration in environment variables, not hardcoded
Related Resources
Related Glossary
Related Lessons
- Connection Pooling
Learn about database connections.