Fix PostgreSQL Connection Refused: psql: error: connection to server on host "localhost" (127.0.0.1), port 5432 failed: Connection refused

TL;DR Quick Fix

Often, this error indicates that your PostgreSQL server isn't running or isn't configured to accept connections from your client. First, try restarting your PostgreSQL service:

sudo systemctl start postgresql
# Or, if it's already running, restart it
sudo systemctl restart postgresql

If a simple restart doesn't resolve it, the problem often lies with an incorrect pg_hba.conf configuration. You'll need to ensure your client's IP address (or localhost) has permission to connect.

Detailed Root Cause

The error message:

psql: error: connection to server on host "localhost" (127.0.0.1), port 5432 failed: Connection refused

This message means your client application (psql) tried to connect to the PostgreSQL server on localhost (127.0.0.1), port 5432. However, the server explicitly rejected the connection attempt. It's important to note this is different from a connection timeout, which happens when the server doesn't respond at all.

Why does this happen? Here are the most common culprits behind a "Connection refused" error:

• PostgreSQL Server Not Running: This is the simplest explanation. If the PostgreSQL service isn't active, there's nothing available to accept connections.
• Incorrect listen_addresses in postgresql.conf: PostgreSQL often defaults to listening only on localhost. If you're trying to connect from another machine, or if the listen_addresses setting is wrong, connections will be denied.
• Improper Authentication Configuration in pg_hba.conf: Even if the server is running and listening, it relies on pg_hba.conf (Host-Based Authentication) to manage client access. This file specifies which hosts can connect, to which databases, with which users, and using what authentication methods. If your client's connection doesn't align with an approved entry, access will be refused.
• Firewall Blocking Connections: A firewall (like ufw or firewalld on Linux, or Windows Firewall) could be blocking incoming connections to port 5432 on the server.
• Incorrect Port Number: The PostgreSQL server might be operating on a port other than the standard 5432. If your client tries to connect to the wrong port, it will fail.

Fix Approaches

1. Verify PostgreSQL Service Status

Let's start by confirming your PostgreSQL server is actually running. The exact commands you'll use depend on your operating system and how PostgreSQL was installed.

Linux (systemd-based distributions like Ubuntu, Debian, CentOS 7+, Fedora):

# Check status
sudo systemctl status postgresql

# If it's not running, start it
sudo systemctl start postgresql

# If it's running but you suspect issues, restart it
sudo systemctl restart postgresql

# Enable to start on boot
sudo systemctl enable postgresql

macOS (Homebrew installation):

# Start PostgreSQL
brew services start postgresql

# Restart PostgreSQL
brew services restart postgresql

# Check status
brew services list | grep postgresql

2. Check postgresql.conf for listen_addresses

The listen_addresses parameter in postgresql.conf dictates which network interfaces PostgreSQL monitors for incoming connections. If it's configured for 'localhost' and you're trying to connect from a remote machine (or even a Docker container on the same host), your connection will be refused.

Locate postgresql.conf:

# For Debian/Ubuntu
sudo find / -name postgresql.conf 2>/dev/null
# Common paths: /etc/postgresql/<version>/main/postgresql.conf

# For macOS (Homebrew)
# /usr/local/var/postgres/postgresql.conf

Once you've found the file, open it and locate the listen_addresses line:

#postgresql.conf
listen_addresses = 'localhost'       # what IP address(es) to listen on;

To permit connections from any IP address, change it to the following. Be cautious with this setting; always combine it with robust pg_hba.conf rules for proper security:

#postgresql.conf
listen_addresses = '*'

After making this change, remember to restart PostgreSQL:

sudo systemctl restart postgresql

3. Configure Host-Based Authentication in pg_hba.conf

pg_hba.conf is PostgreSQL's client authentication configuration file. It's the rulebook for who can connect, from where, to which databases, and with what authentication method.

Locate pg_hba.conf: This file is typically found in the same directory as postgresql.conf.

Open pg_hba.conf. You'll need to add or modify entries to permit your connection. Below are some common examples to guide you:

To allow local connections (from the same machine) using a password:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5

To allow a connection from a specific IP address (e.g., 192.168.1.100) using a password:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             192.168.1.100/32        md5

To allow connections from an entire network subnet (e.g., any host within 192.168.1.0/24) using a password:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             192.168.1.0/24          md5

To allow all connections (use with extreme caution and only for development environments!):

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             0.0.0.0/0               md5

Important: For stronger password security, replace md5 with scram-sha-256, especially if you're using PostgreSQL 10 or newer. Crucially, make sure you've set up a user with a password. For instance, you might use ALTER USER youruser WITH PASSWORD 'yourpassword'; to set one.

Once you've made these changes, reload PostgreSQL's configuration. A full restart isn't necessary for pg_hba.conf updates:

sudo systemctl reload postgresql

4. Check Firewall Rules

Your system's firewall could be blocking incoming connections to PostgreSQL's default port, 5432.

Linux (UFW - Uncomplicated Firewall, common on Ubuntu/Debian):

# Check UFW status
sudo ufw status verbose

# Allow connections on port 5432 (default PostgreSQL port)
sudo ufw allow 5432/tcp

# Or allow from a specific IP address
sudo ufw allow from 192.168.1.100 to any port 5432

# Reload UFW to apply changes
sudo ufw reload

Linux (firewalld, common on CentOS/RHEL/Fedora):

# Check firewalld status
sudo firewall-cmd --state

# Allow connections on port 5432
sudo firewall-cmd --add-port=5432/tcp --permanent
sudo firewall-cmd --reload

Windows Firewall:

On Windows, you'll need to manually configure your firewall. Open Windows Defender Firewall with Advanced Security. Navigate to Inbound Rules, then create a new rule to allow TCP connections specifically on port 5432.

5. Verify Port Number

Always double-check that your client application is attempting to connect to the correct port. While 5432 is the default, this can be altered in your postgresql.conf file:

#postgresql.conf
port = 5432                            # (change requires restart)

If you modify this setting, you must restart your PostgreSQL service for the change to take effect.

If PostgreSQL isn't running on the default port, remember to specify it when connecting with psql:

psql -h localhost -p 5432 -U your_user -d your_database

Verification Steps

Once you've applied a fix, it's time to verify. Try connecting to your PostgreSQL server again using psql:

psql -h localhost -U postgres -d postgres

Remember to replace localhost, postgres (for the user), and postgres (for the database) with your specific connection details. If everything worked, you'll be prompted for a password (if configured) and then welcomed by the psql command prompt, usually looking like postgres=#.

Still encountering problems? Dig into the PostgreSQL server logs for more granular error messages. These often provide crucial clues. Log file locations aren't always consistent, but you'll frequently find them in directories like /var/log/postgresql/ or directly within your PostgreSQL data directory.

Further Reading

• PostgreSQL Documentation: The pg_hba.conf File
• PostgreSQL Documentation: listen_addresses
• PostgreSQL Documentation: Client Authentication