How to Fix PostgreSQL 'FATAL: password authentication failed for user' Error

🔍 Quick Diagnostics

🚀 How to Fix the Error Step-by-Step

Step 1: Connect via local UNIX socket as the system postgres user

On Linux environments, the default PostgreSQL superuser (postgres) uses peer authentication over local UNIX sockets. Access the interactive prompt directly by switching system users:

# Switch to the postgres system user and launch psql
sudo -u postgres psql

If the command succeeds and drops you into the postgres=# prompt, the PostgreSQL daemon is functioning properly; the failure is isolated to TCP/IP password authentication.

Step 2: Reset the PostgreSQL user role password

From the interactive psql shell, set a new password for the target database role (such as postgres or your application user):

-- Change password for the postgres database user
ALTER USER postgres WITH PASSWORD 'YourNewSecurePassword123!';

Exit the interactive terminal using \q.

Step 3: Configure client authentication in pg_hba.conf

Open PostgreSQL's client authentication configuration file (pg_hba.conf). You can locate its path by running SHOW hba_file; inside psql or looking in /etc/postgresql/:

# Example for PostgreSQL 15/16 on Debian/Ubuntu
sudo nano /etc/postgresql/16/main/pg_hba.conf

Inspect access control entries for local and TCP/IP loopback connections (127.0.0.1/32 or ::1/128). Ensure they use scram-sha-256 or md5:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
# Local UNIX socket connections
local   all             postgres                                peer
local   all             all                                     md5

# IPv4 local connections (TCP/IP)
host    all             all             127.0.0.1/32            scram-sha-256

# IPv6 local connections
host    all             all             ::1/128                 scram-sha-256

Step 4: Reload the PostgreSQL service

Reload the PostgreSQL service to apply changes made to pg_hba.conf without terminating existing active client connections:

# Reload configuration on your Linux server
sudo systemctl reload postgresql

Test password authentication via TCP/IP using the -h localhost parameter:

psql -h localhost -U postgres -W