Skip to content

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

✗ Broken code
# Connecting to a server that is not running
psql -h localhost -p 5432 -U postgres
# → connection refused
✓ Fixed code
# Start the server first, then connect
pg_ctl start
psql -h localhost -p 5432 -U postgres

The server was not running. Starting it first allows the connection to succeed.

How to diagnose

  • Check if the database service is running: pg_isready for PostgreSQL or mysqladmin ping for MySQL

  • Verify 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

← Back to language