Error: Authentication Failed Troubleshooting Guide

When using MCP postgres tool and encountering Authentication failed error, identity verification failed.

Error Symptoms

Error: Authentication failed for user 'username'
Error: password authentication failed for user 'username'

Causes

1. Wrong username or password
2. pg_hba.conf configuration issue
3. User does not exist or no permission
4. Authentication method mismatch

Troubleshooting Steps

Step 1: Check Username and Password

Verify connection string

{
  "mcpServers": {
    "postgres": {
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://username:password@localhost/dbname"
      ]
    }
  }
}

Common errors

• Username typo
• Special characters in password not escaped
• Wrong database name

Step 2: Check pg_hba.conf Configuration

Find config file

ps aux | grep config_file

Check authentication method

cat /path/to/pg_hba.conf | grep -v "^#" | grep -v "^$"

Common configuration

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

Step 3: Check User Exists

Check users with psql

psql -U postgres\du

Create user

CREATE USER username WITH PASSWORD 'password';
GRANT CONNECT ON DATABASE dbname TO username;

Step 4: Check User Permissions

View permissions

Grant permissions

GRANT SELECT ON tablename TO username;
GRANT ALL PRIVILEGES ON DATABASE dbname TO username;

Step 5: Restart PostgreSQL

brew services restart postgresql  # macOS
sudo systemctl restart postgresql  # Linux

FAQ

Q: Password correct but still authentication failed?
A: Check pg_hba.conf allows connection, authentication method matches.

Q: How to reset user password?
A: \password username or ALTER USER username WITH PASSWORD 'newpassword';

Q: How to view current authentication config?
A: cat /path/to/pg_hba.conf

Verify Fix

1. Confirm username and password correct
2. Confirm pg_hba.conf allows connection
3. Confirm user has database permissions
4. Restart PostgreSQL
5. Test with psql
6. Restart Claude Code

Next Steps

• PostgreSQL Configuration
• Connection Refused Error
• Filesystem Configuration