{
  "id": "art_Rb714qFVQc7G",
  "slug": "error-authentication-failed-troubleshooting-guide",
  "author": "句芒（goumang）",
  "title": "Error: Authentication Failed Troubleshooting Guide",
  "summary": "Complete troubleshooting workflow for PostgreSQL Authentication failed error, including password issues, pg_hba.conf configuration, and user permissions.",
  "content": "# Error: Authentication Failed Troubleshooting Guide\n\nWhen using MCP postgres tool and encountering Authentication failed error, identity verification failed.\n\n## Error Symptoms\n\n```\nError: Authentication failed for user 'username'\nError: password authentication failed for user 'username'\n```\n\n## Causes\n\n1. Wrong username or password\n2. pg_hba.conf configuration issue\n3. User does not exist or no permission\n4. Authentication method mismatch\n\n## Troubleshooting Steps\n\n### Step 1: Check Username and Password\n\n**Verify connection string**\n```json\n{\n  \"mcpServers\": {\n    \"postgres\": {\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-postgres\",\n        \"postgresql://username:password@localhost/dbname\"\n      ]\n    }\n  }\n}\n```\n\n**Common errors**\n- Username typo\n- Special characters in password not escaped\n- Wrong database name\n\n### Step 2: Check pg_hba.conf Configuration\n\n**Find config file**\n```bash\nps aux | grep config_file\n```\n\n**Check authentication method**\n```bash\ncat /path/to/pg_hba.conf | grep -v \"^#\" | grep -v \"^$\"\n```\n\n**Common configuration**\n```\n# TYPE  DATABASE        USER            ADDRESS                 METHOD\nhost    all             all             127.0.0.1/32            md5\nhost    all             all             ::1/128                 md5\n```\n\n### Step 3: Check User Exists\n\n**Check users with psql**\n```bash\npsql -U postgres\\du\n```\n\n**Create user**\n```sql\nCREATE USER username WITH PASSWORD 'password';\nGRANT CONNECT ON DATABASE dbname TO username;\n```\n\n### Step 4: Check User Permissions\n\n**View permissions**\n```sql\\dp\\l\\z tablename\n```\n\n**Grant permissions**\n```sql\nGRANT SELECT ON tablename TO username;\nGRANT ALL PRIVILEGES ON DATABASE dbname TO username;\n```\n\n### Step 5: Restart PostgreSQL\n\n```bash\nbrew services restart postgresql  # macOS\nsudo systemctl restart postgresql  # Linux\n```\n\n## FAQ\n\n**Q: Password correct but still authentication failed?**\nA: Check pg_hba.conf allows connection, authentication method matches.\n\n**Q: How to reset user password?**\nA: \\password username or ALTER USER username WITH PASSWORD 'newpassword';\n\n**Q: How to view current authentication config?**\nA: cat /path/to/pg_hba.conf\n\n## Verify Fix\n\n1. Confirm username and password correct\n2. Confirm pg_hba.conf allows connection\n3. Confirm user has database permissions\n4. Restart PostgreSQL\n5. Test with psql\n6. Restart Claude Code\n\n## Next Steps\n\n- [PostgreSQL Configuration](TOOL-PG-001)\n- [Connection Refused Error](TOOL-PG-002)\n- [Filesystem Configuration](TOOL-FS-001)",
  "lang": "en",
  "domain": "mcp",
  "tags": [
    "mcp",
    "postgres",
    "error",
    "authentication-failed"
  ],
  "keywords": [
    "mcp",
    "postgres",
    "authentication-failed",
    "password",
    "pg_hba.conf"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 98,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "What does Authentication failed mean?",
      "answer": "Username or password incorrect, or pg_hba.conf does not allow connection."
    },
    {
      "id": "qa_002",
      "question": "How to reset PostgreSQL user password?",
      "answer": "Use ALTER USER username WITH PASSWORD 'newpassword'; or \\password command."
    },
    {
      "id": "qa_003",
      "question": "Do I need to restart after modifying pg_hba.conf?",
      "answer": "Yes, must restart PostgreSQL service to take effect."
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmnd2pbd0004iwcxaqtzomfs",
      "articleId": "art_Rb714qFVQc7G",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T11:05:04.682Z"
    },
    {
      "id": "cmmnd2hu10002iwcxkfvnspcz",
      "articleId": "art_Rb714qFVQc7G",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T11:04:54.986Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T11:04:52.851Z",
  "updatedAt": "2026-04-04T18:25:08.661Z",
  "createdAt": "2026-03-12T11:04:51.770Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=error-authentication-failed-troubleshooting-guide",
      "json": "/api/v1/articles/error-authentication-failed-troubleshooting-guide?format=json&lang=en",
      "markdown": "/api/v1/articles/error-authentication-failed-troubleshooting-guide?format=markdown&lang=en"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/error-authentication-failed-troubleshooting-guide?format=json&lang=en\""
  }
}