PostgreSQL "Connection refused" error occurs when the client cannot establish a TCP connection to the server, typically because the PostgreSQL service is not running, not listening on the expected port, or network/firewall restrictions block the connection. Common fixes include starting the PostgreSQL service, verifying listen_addresses configuration, and checking firewall rules.
The "Could not connect to server: Connection refused" error indicates that the PostgreSQL client (psql, application driver, etc.) cannot establish a TCP/IP connection to the PostgreSQL server. This is a network-level error, not a database authentication or permissions error. When you attempt to connect, the OS attempts to establish a socket connection to the specified host and port (default 5432). If the connection is refused, it means either: 1. No process is listening on that address and port 2. The process (PostgreSQL) is listening but explicitly refusing connections 3. Network/firewall rules prevent the connection from reaching the listening socket This differs from "FATAL: Ident authentication failed" (authentication issue) or "FATAL: database "name" does not exist" (database issue). Connection refused happens before authentication, meaning the server is unreachable.
The most common cause of connection refused is that PostgreSQL is not running.
# On Linux/macOS with systemd:
sudo systemctl status postgresql
# On macOS with Homebrew:
brew services list | grep postgresql
# On Windows, check Task Manager > Services for "postgresql-x64-*"
# Alternative: check if port 5432 is listening
sudo netstat -plntu | grep 5432
# or:
sudo ss -plntu | grep 5432If not running, start the service:
# Linux/macOS:
sudo systemctl start postgresql
# macOS Homebrew:
brew services start postgresql
# Windows:
sc start postgresql-x64-14Check the PostgreSQL configuration to ensure it is listening on the address and port you are trying to connect to.
# Find postgresql.conf location:
sudo -u postgres psql -c "SHOW config_file;"
# Typically: /etc/postgresql/14/main/postgresql.conf
# Check listen_addresses:
sudo -u postgres psql -c "SHOW listen_addresses;"
# Should show "*" or the IP you are connecting from
# Check port:
sudo -u postgres psql -c "SHOW port;"
# Should show 5432 (default) or your custom portIf listen_addresses is set to "localhost" and you need remote connections:
# Edit postgresql.conf:
sudo vi /etc/postgresql/14/main/postgresql.conf
# Find the line:
#listen_addresses = 'localhost'
# Change to:
listen_addresses = '*'
# Or specify specific IPs:
listen_addresses = 'localhost, 192.168.1.100'
# Save and restart PostgreSQL:
sudo systemctl restart postgresqlFirewalls often block port 5432 by default, especially for remote connections.
# On Linux with UFW (Ubuntu/Debian):
sudo ufw status
sudo ufw allow 5432/tcp
# On Linux with firewalld (RedHat/CentOS):
sudo firewall-cmd --list-ports
sudo firewall-cmd --permanent --add-port=5432/tcp
sudo firewall-cmd --reload
# On macOS, check System Preferences > Security & Privacy > Firewall Options
# Allow PostgreSQL if blocked
# On Windows, run Windows Defender Firewall with Advanced Security:
# Add an inbound rule for port 5432 (TCP)Verify port is accessible from your client:
# Use telnet or nc to test connectivity:
telnet localhost 5432
# or:
nc -zv localhost 5432
# Should show connection succeeded (not Connection refused)Verify you are connecting to the right server and port.
# Test with psql:
psql -h localhost -U postgres -d postgres
# or
psql -h 127.0.0.1 -p 5432 -U postgres -d postgres
# For remote connections, use the server IP or hostname:
psql -h 192.168.1.100 -p 5432 -U postgres -d postgresIf connecting from an application, check the connection string:
// Node.js/JavaScript
const client = new Client({
host: "localhost", // Change to remote IP if needed
port: 5432, // Verify this matches postgresql.conf
user: "postgres",
database: "postgres"
});Common hostname mistakes:
- Using "localhost" when connecting from a Docker container (should be the container hostname or network IP)
- Using "127.0.0.1" which only works for local connections
- Typos in the hostname or IP address
If local connections work but remote connections fail, the issue is in authentication rules, not the service.
# Find pg_hba.conf:
sudo -u postgres psql -c "SHOW hba_file;"
# Typically: /etc/postgresql/14/main/pg_hba.conf
# View current rules:
sudo cat /etc/postgresql/14/main/pg_hba.confThe file contains rules like:
local all all trust
host all all 127.0.0.1/32 md5
host all all ::1/128 md5Add a rule for your remote network:
# Allow connections from a specific subnet:
host all all 192.168.1.0/24 md5
# Or from anywhere (less secure):
host all all 0.0.0.0/0 md5After editing pg_hba.conf, reload PostgreSQL:
sudo -u postgres psql -c "SELECT pg_reload_conf();";
# or restart:
sudo systemctl restart postgresqlPostgreSQL logs often contain more detailed information about why the server is not accepting connections.
# On Linux, check the error log:
tail -50 /var/log/postgresql/postgresql-14-main.log
# Or query the log directory:
sudo -u postgres psql -c "SHOW log_directory;"
# Real-time log monitoring:
sudo tail -f /var/log/postgresql/postgresql-14-main.logLook for messages like:
- "could not bind IPv4 socket: Address already in use" (port conflict)
- "could not create socket" (network issue)
- "permission denied" (startup permission issue)
If PostgreSQL fails to start, check the startup errors and address the root cause before attempting to connect.
After making any configuration changes, restart PostgreSQL and test the connection.
# Restart PostgreSQL:
sudo systemctl restart postgresql
# Wait a few seconds for startup:
sleep 2
# Test local connection:
psql -U postgres -d postgres -c "SELECT version();"
# Test remote connection (if applicable):
psql -h <remote-ip> -U postgres -d postgres -c "SELECT version();"
# In your application, test the connection string:
node test-connection.jsIf connection still fails, review the error message carefully—it often indicates whether the issue is networking (connection refused), authentication (password or ident), or database-specific (database does not exist).
For Docker Compose: PostgreSQL services must be on the same network. If your application container cannot connect to PostgreSQL, ensure both are defined in the same docker-compose.yml service section. Use the service name as the hostname (not localhost). Example: psql -h postgres -U postgres (where "postgres" is the service name).
For containerized environments: The host "localhost" inside a container refers to the container itself, not the host machine. Use the Docker network IP, service name, or volume-mounted socket for connections.
For SSL/TLS connections: Some clients require sslmode=require or sslmode=allow. If you see "Connection refused" on a non-standard port, verify the port is actually PostgreSQL (not a reverse proxy or connection pooler like pgBouncer).
For connection poolers (pgBouncer, PgPool-II): These act as a proxy to PostgreSQL. If the pooler is running but connection refused errors persist, verify the pooler is configured to connect to the actual PostgreSQL server correctly.
On cloud platforms (AWS RDS, Azure Database, Heroku): The hostname is typically a fully qualified domain name (e.g., "mydb.c9akciq32.us-east-1.rds.amazonaws.com"). Verify the security group/network ACL allows inbound traffic on port 5432 from your IP. Also check that you are connecting to the correct endpoint (writer vs. reader in RDS).
insufficient columns in unique constraint for partition key
How to fix "insufficient columns in unique constraint for partition key" in PostgreSQL
ERROR 42501: must be owner of table
How to fix "must be owner of table" in PostgreSQL
trigger cannot change partition destination
How to fix "Trigger cannot change partition destination" in PostgreSQL
SSL error: certificate does not match host name
SSL error: certificate does not match host name in PostgreSQL
No SSL connection
No SSL connection to PostgreSQL