inchTodd/db-error-troubleshooting-skills / skills/pg-password-authentication-failed
pg-password-authentication-failed
Verified排查 PostgreSQL 报错「password authentication failed for user "%s"」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.9 KB |
SKILL.md
View on GitHub---
name: pg-password-authentication-failed
description: "排查 PostgreSQL 报错「password authentication failed for user \"%s\"」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。"
---
# PostgreSQL「password authentication failed」:客户端只告诉你失败,原因在服务器日志的 DETAIL 里
> 原文与完整版:https://surinch.com/tools/postgresql-error/password-authentication-failed(最后核对 2026-11-04)
## 一句话结论
这条报错出现在 `pg_hba.conf` 已经匹配到一条 `scram-sha-256`、`md5` 或 `password` 规则之后,说明是**密码这一步没过**。为了不泄露信息,客户端看到的永远是同一句话;连用户不存在也报这句。先去服务器日志找紧跟其后的 `DETAIL`,它会写明是角色不存在、没设密码、密码过期还是密码不匹配,再对症处理。
## 官方报错原文
```
password authentication failed for user "%s"
```
出自 auth.c 的 auth_failed(),`password`、`md5`、`scram-sha-256` 三种方式失败都用这句,错误码 `ERRCODE_INVALID_PASSWORD`(SQLSTATE 28P01)。
## 关键事实
| 项 | 内容 |
|---|---|
| SQLSTATE | `28P01`(invalid_password) |
| 前提 | 已经命中 pg_hba.conf 里的密码类规则;没命中是 no pg_hba.conf entry |
| 用户不存在时 | 客户端仍报 password authentication failed,日志 DETAIL 写 Role does not exist |
| PG14 起默认 | `password_encryption = scram-sha-256` |
| md5 状态 | MD5 密码已标记弃用,将在未来版本移除 |
## 第一步:看服务器日志里的 DETAIL
官方文档的建议是查服务器日志:日志里的信息比客户端多。下面是 PostgreSQL 18 源码 crypt.c 和 auth.c 里会跟在这条报错后面的 DETAIL,以及各自的处理办法:
| 日志 DETAIL | 意思 | 怎么改 |
|---|---|---|
| `Role "x" does not exist.` | 没有这个数据库用户(客户端看不出来) | 检查用户名拼写和大小写;需要时 `CREATE ROLE x LOGIN PASSWORD '...'` |
| `User "x" has no password assigned.` | 用户存在,但从来没设过密码 | `ALTER ROLE x PASSWORD '...'`,或在 psql 里 `\password x` |
| `User "x" has an expired password.` | `VALID UNTIL` 已过期 | `ALTER ROLE x VALID UNTIL 'infinity';` 或设一个新的到期时间 |
| `User "x" has a password that cannot be used with MD5 authentication.` | 客户端/规则走 MD5,但存的密码不是 MD5 格式 | 见下一节:通常把规则改成 scram-sha-256 |
| `Password does not match for user "x".` | 密码确实不对 | 核对连接串、环境变量 `PGPASSWORD`、`~/.pgpass` 里是否有旧密码 |
| `Connection matched file "..." line N: "..."` | 命中的是哪一条 pg_hba 规则(PG16 起带文件名) | 确认命中的规则是你以为的那条 |
```sql
SHOW log_directory;
SHOW log_destination;
SELECT pg_current_logfile();
```
## md5 与 scram-sha-256:升级后最常见的坑
密码以什么格式保存,由**设置密码那一刻**的 `password_encryption` 决定。PG14 起默认是 `scram-sha-256`,PG13 及以前默认是 `md5`。官方文档给出的兼容关系:
| 存的密码格式 | pg_hba 写 scram-sha-256 | pg_hba 写 md5 | pg_hba 写 password |
|---|---|---|---|
| SCRAM | 可以 | 可以(自动改用 SCRAM 认证) | 可以(明文传输) |
| MD5 | **不行** | 可以 | 可以(明文传输) |
所以“升级或迁移后突然登不上”,常见原因是:旧库里的密码是 MD5 格式,而新环境的规则写成了 `scram-sha-256`。官方给的迁移步骤是:确认客户端驱动支持 SCRAM,设 `password_encryption = 'scram-sha-256'`,**让所有用户重新设置一次密码**,再把规则改成 `scram-sha-256`。
```sql
-- 只读:看哪些用户还是 MD5 密码(需要超级用户)
SELECT rolname,
CASE WHEN rolpassword LIKE 'SCRAM-SHA-256$%' THEN 'scram-sha-256'
WHEN rolpassword LIKE 'md5%' THEN 'md5'
WHEN rolpassword IS NULL THEN '未设置'
ELSE '其他' END AS password_format,
rolvaliduntil
FROM pg_authid
WHERE rolcanlogin
ORDER BY rolname;
```
```sql
SET password_encryption = 'scram-sha-256';
ALTER ROLE app PASSWORD '请换成新密码';
```
> PG18 在设置 MD5 格式密码时会给出警告:MD5 password support is deprecated and will be removed in a future release of PostgreSQL。还在用 md5 规则的库,升级前一并迁移。
## 密码明明没错:先排除客户端拿错了密码
- **`PGPASSWORD` 环境变量和 `~/.pgpass`**:libpq 会自动使用它们,命令行看起来没输密码,其实传了一个旧密码。用 `env | grep PG` 和检查 `~/.pgpass` 排除。
- **连接串里的特殊字符**:URI 形式的连接串中,密码里的 `@`、`:`、`/`、`#` 要做百分号编码,否则被截断。
- **大小写**:不加双引号建的角色名会被转成小写;`CREATE ROLE "App"` 建的用户登录时用户名必须是 `App`。
- **连错实例**:同一台机器上有多个集群(Debian 的 5432、5433……)时,先 `SELECT inet_server_port(), version();` 确认。
- **连接池**:经过 PgBouncer 等中间件时,失败可能发生在中间件那一层,它有自己的用户和密码配置。
确认密码本身没问题后,如果日志里是 `Connection matched` 的行号不是你预期的那条,回到 [no pg_hba.conf entry](https://surinch.com/tools/postgresql-error/no-pg-hba-conf-entry) 一页检查规则顺序。
## 常见问题
**password authentication failed for user "postgres" 怎么办?**
先查服务器日志里紧跟着的 DETAIL:如果是 has no password assigned,用 sudo -u postgres psql 登录后 \password postgres 设密码;如果是 Password does not match,检查 PGPASSWORD 和 ~/.pgpass 是否带了旧密码。
**用户不存在为什么也报 password authentication failed?**
这是有意的设计,避免让外部探测出哪些用户名存在。服务器日志的 DETAIL 会写 Role does not exist。
**升级到 PG14 以后密码登录失败?**
PG14 起 password_encryption 默认 scram-sha-256。如果旧密码是 MD5 格式而 pg_hba 写的是 scram-sha-256,就会失败。让用户重新设置一次密码,或者暂时把规则写成 md5(md5 规则对 SCRAM 密码也能用)。
**28P01 是什么错误码?**
SQLSTATE 28P01 是 invalid_password,PostgreSQL 在 password、md5、scram-sha-256 认证失败时返回。应用里可以按这个码把“密码错”和其他连接错误分开处理。
**DBeaver / Navicat 连 PostgreSQL 提示密码错误?**
先确认用户名大小写、端口是否连到了正确的集群,再看服务器日志的 DETAIL。较老的客户端驱动可能不支持 SCRAM,需要升级驱动。
## 给 agent 的使用守则
- 先让用户贴出完整报错和执行的命令,按上面的顺序做只读检查,再给修改建议。
- 不要求用户提供密码、连接串里的凭证或生产数据;需要时让用户自己在本机执行命令并贴结果(可先打码)。
- 改配置(pg_hba.conf、my.cnf、授权语句)前先说明影响并让用户确认;本 skill 不承诺任何修复效果。
## 来源
- [PostgreSQL 源码 REL_18_STABLE:src/backend/libpq/auth.c(auth_failed)](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/libpq/auth.c)
- [PostgreSQL 源码 REL_18_STABLE:src/backend/libpq/crypt.c](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/libpq/crypt.c)
- [PostgreSQL 18 文档 20.5:Password Authentication](https://www.postgresql.org/docs/current/auth-password.html)
- [PostgreSQL 14 文档 20.3:password_encryption(默认 scram-sha-256)](https://www.postgresql.org/docs/14/runtime-config-connection.html)
- [PostgreSQL 18 文档 20.16:Authentication Problems](https://www.postgresql.org/docs/current/client-authentication-problems.html)
完整图文版和相关报错:https://surinch.com/tools/postgresql-error/password-authentication-failed
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |