How to fix Connection failure in PostgreSQL

PostgreSQLINTERMEDIATEHIGHUpdated Dec 25, 2025· 259 views

PostgreSQL connection failure occurs when a client cannot establish a connection to the database server. This can happen due to the server being down, incorrect connection parameters, network issues, or authentication problems.

Quick fix

Fixes Connection failure

# Check service status
sudo systemctl status postgresql

# If not running, start it
sudo systemctl start postgresql
  1. Verify PostgreSQL server is running
  2. Check PostgreSQL port configuration
  3. Verify listen_addresses in postgresql.conf
  4. Check pg_hba.conf authentication rules
postgresql — error
# Check service status
sudo systemctl status postgresql
# If not running, start it
sudo systemctl start postgresql
Connection failure

What this error means

A PostgreSQL connection failure means the client application failed to establish a TCP connection to the PostgreSQL server. This is a fundamental networking or server availability issue that prevents any database operations from occurring. The error occurs before authentication or query execution, indicating either the server is unreachable, not listening on the expected port, or a firewall is blocking the connection. The specific cause depends on whether you're connecting locally via Unix socket or remotely via TCP/IP. Local connections may fail due to missing socket files or permission issues, while remote connections typically fail due to server not running, listening on wrong port, or firewall restrictions.

Typical symptoms

  • Cannot connect to PostgreSQL database from any client
  • Application logs show 'connection refused' or 'could not connect to server'
  • psql command-line tool fails immediately without authenticating
  • Connection timeout after several seconds of waiting
  • Different error for local socket vs TCP connections
  • Connecting to one port works but another doesn't

Common causes

  1. PostgreSQL server process is not running or has crashed
  2. Server is listening on a different port than the client expects (default is 5432)
  3. Firewall or network ACL is blocking the connection port
  4. TCP/IP connections are disabled in postgresql.conf (listen_addresses misconfiguration)
  5. Client is using wrong hostname, IP address, or socket path
  6. PostgreSQL server crashed or failed to start due to corrupted data or configuration
  7. Maximum connections limit has been reached and new connections are rejected
  8. Network connectivity issue between client and server host
  9. PostgreSQL listening only on localhost but client connecting from remote network

How to fix "Connection failure"

1Verify PostgreSQL server is running

Check if the PostgreSQL service is active and running.

On Linux/macOS:

bash
# Check service status
sudo systemctl status postgresql

# If not running, start it
sudo systemctl start postgresql

On macOS with Homebrew:

bash
brew services list
brew services start postgresql

On Windows:

bash
# Check in Services application or use:
net start postgresql-x64-14

If the service won't start, check the PostgreSQL logs for startup errors. The log location is typically /var/log/postgresql/ on Linux or in the PostgreSQL data directory.

2Check PostgreSQL port configuration

Verify the server is listening on the port you're connecting to.

bash
# Check what port PostgreSQL is listening on
sudo netstat -tlnp | grep postgres

# Or with ss (newer systems)
sudo ss -tlnp | grep postgres

The output should show PostgreSQL listening on port 5432 (default) or your custom port. If nothing appears, PostgreSQL is not listening on TCP/IP.

If using a non-standard port, ensure your connection string includes it:

bash
psql -h localhost -p 5433 -U username -d database
3Verify listen_addresses in postgresql.conf

PostgreSQL must be configured to accept TCP/IP connections.

1. Find and edit the postgresql.conf file:

bash
# Find the file location
sudo -u postgres psql -c "SHOW config_file"

# Edit it (commonly at /etc/postgresql/14/main/postgresql.conf)
sudo nano /etc/postgresql/14/main/postgresql.conf

2. Find the listen_addresses setting. It should be:

bash
listen_addresses = '*'  # Listen on all interfaces

If it's set to localhost only, remote connections will fail. The * value allows connections from any network interface.

3. Save and restart PostgreSQL:

bash
sudo systemctl restart postgresql
4Check pg_hba.conf authentication rules

The pg_hba.conf file controls which hosts can connect. Verify your client IP is allowed.

1. Find and edit the file:

bash
# Commonly at:
sudo nano /etc/postgresql/14/main/pg_hba.conf

2. Look for a line matching your connection type. For TCP/IP connections from localhost:

bash
# IPv4 local connections:
host    all             all             127.0.0.1/32            md5

# IPv6 local connections:
host    all             all             ::1/128                 md5

3. For remote connections, you need an entry like:

bash
# Allow from specific IP
host    all             all             192.168.1.100/32        md5

# Or allow from entire subnet
host    all             all             192.168.1.0/24          md5

4. Save and reload PostgreSQL:

bash
sudo systemctl reload postgresql

Note: Lines are processed top-to-bottom, so place more specific entries before general ones.

5Test connectivity with telnet or nc

Before troubleshooting PostgreSQL internals, test basic network connectivity:

bash
# Test with telnet (if installed)
telnet localhost 5432

# Or with netcat
nc -zv localhost 5432

# For remote server
nc -zv 192.168.1.50 5432

If you get 'Connection refused' or timeout, the server isn't listening. If it connects, PostgreSQL is reachable but the client may have wrong credentials or pg_hba.conf issues.

Check firewall if connecting remotely:

bash
# On Linux with ufw
sudo ufw allow 5432/tcp

# Or with iptables
sudo iptables -A INPUT -p tcp --dport 5432 -j ACCEPT
6Verify connection string parameters

Ensure your application is using correct connection parameters.

Common formats:

bash
postgresql://username:password@localhost:5432/dbname
host=localhost port=5432 user=postgres password=secret dbname=mydb

Verify each parameter:
- host: Should be 'localhost' for local Unix socket, or IP/hostname for TCP
- port: Default is 5432; verify it matches your postgresql.conf
- user: Must be a valid PostgreSQL role
- password: Must match the user's password
- dbname: Database must exist

Test with psql directly:

bash
psql -h localhost -p 5432 -U postgres -d postgres

If this works, your connection parameters are correct. If not, you've found the issue in one of the above steps.

7Check for max_connections limit

If PostgreSQL was running but now rejects all connections, the max_connections limit may be reached.

bash
# Connect as superuser (if you can)
sudo -u postgres psql

# View current setting
SHOW max_connections;

# View active connections
SELECT count(*) FROM pg_stat_activity;

# Terminate idle connections
SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE pid <> pg_backend_pid() AND state = 'idle';

To increase the limit:
1. Edit postgresql.conf and change max_connections
2. Restart PostgreSQL: sudo systemctl restart postgresql

Note: Each connection uses system resources. Setting it too high can cause performance issues.

Advanced notes

Unix Socket vs TCP/IP: PostgreSQL supports two connection methods. Local Unix socket connections (default on some systems) are faster but require the socket file to exist at the expected location (usually /var/run/postgresql/ or /tmp/). If you see 'could not connect to server: No such file or directory' with local connections, check the unix_socket_directories setting in postgresql.conf.

SSL/TLS Connections: If your application requires SSL, PostgreSQL must be compiled with SSL support. Check with psql --version or SHOW ssl; in psql. SSL connection failures appear similar to general connection failures but are distinguished in the logs.

Replication and Streaming: If this error occurs during streaming replication setup, verify that the replication role is created, has REPLICATION privilege, and pg_hba.conf has a matching entry with the replication keyword.

Container/Cloud Deployments: In Docker or cloud environments (AWS RDS, Azure Database for PostgreSQL), connection failures are often due to security groups/network ACLs not allowing traffic, or the server endpoint being incorrect. Always verify the endpoint URL and port from your cloud provider's console.

Connection Pool Exhaustion: With application connection pools (pgBouncer, PgPool-II), a full pool can look like a connection failure. Check the pool's configuration and connection counts before investigating PostgreSQL itself.

Frequently asked questions

What does "Connection failure" mean?
A PostgreSQL connection failure means the client application failed to establish a TCP connection to the PostgreSQL server. This is a fundamental networking or server availability issue that prevents any database operations from occurring. The error occurs before authentication or query execution, indicating either the server is unreachable, not listening on the expected port, or a firewall is blocking the connection.
How do I fix "Connection failure"?
PostgreSQL connection failure occurs when a client cannot establish a connection to the database server. This can happen due to the server being down, incorrect connection parameters, network issues, or authentication problems.
What causes "Connection failure"?
PostgreSQL server process is not running or has crashed Server is listening on a different port than the client expects (default is 5432) Firewall or network ACL is blocking the connection port
Is the "Connection failure" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading