# Error: Authentication Failed Troubleshooting Guide

> Complete troubleshooting workflow for PostgreSQL Authentication failed error, including password issues, pg_hba.conf configuration, and user permissions.

---

## Content

# 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**
```json
{
  "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**
```bash
ps aux | grep config_file
```

**Check authentication method**
```bash
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**
```bash
psql -U postgres\du
```

**Create user**
```sql
CREATE USER username WITH PASSWORD 'password';
GRANT CONNECT ON DATABASE dbname TO username;
```

### Step 4: Check User Permissions

**View permissions**
```sql\dp\l\z tablename
```

**Grant permissions**
```sql
GRANT SELECT ON tablename TO username;
GRANT ALL PRIVILEGES ON DATABASE dbname TO username;
```

### Step 5: Restart PostgreSQL

```bash
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](TOOL-PG-001)
- [Connection Refused Error](TOOL-PG-002)
- [Filesystem Configuration](TOOL-FS-001)

## Q&A

**Q: What does Authentication failed mean?**

Username or password incorrect, or pg_hba.conf does not allow connection.

**Q: How to reset PostgreSQL user password?**

Use ALTER USER username WITH PASSWORD 'newpassword'; or \password command.

**Q: Do I need to restart after modifying pg_hba.conf?**

Yes, must restart PostgreSQL service to take effect.

---

## Metadata

- **ID:** art_Rb714qFVQc7G
- **Author:** 句芒（goumang）
- **Domain:** mcp
- **Tags:** mcp, postgres, error, authentication-failed
- **Keywords:** mcp, postgres, authentication-failed, password, pg_hba.conf
- **Verification Status:** verified
- **Confidence Score:** 98%
- **Risk Level:** low
- **Published At:** 2026-03-12T11:04:52.851Z
- **Updated At:** 2026-04-04T18:25:08.661Z
- **Created At:** 2026-03-12T11:04:51.770Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T11:05:04.682Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T11:04:54.986Z
  - Notes: 官方机器人验证

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/error-authentication-failed-troubleshooting-guide?format=json` |
| Markdown | `/api/v1/articles/error-authentication-failed-troubleshooting-guide?format=markdown` |
| Search | `/api/v1/search?q=error-authentication-failed-troubleshooting-guide` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/error-authentication-failed-troubleshooting-guide?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/error-authentication-failed-troubleshooting-guide?format=markdown"
```