PostgreSQL · 错误码速查
PostgreSQL「password authentication failed」：客户端只告诉你失败，原因在服务器日志的 DETAIL 里
这条报错出现在 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）。
出处：PostgreSQL 源码 REL_18_STABLE：src/backend/libpq/auth.c（auth_failed） 最后核对：
| 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 起带文件名） | 确认命中的规则是你以为的那条 |
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。
-- 只读：看哪些用户还是 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;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 一页检查规则顺序。
常见问题
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，需要升级驱动。
免费 · 留邮箱领检查单
PostgreSQL 14 停更升级检查单（Excel 可直接打开）
- PG14 2026-11-12 停更，升 17 / 18 前后 19 项检查：只读预检、--check、回滚、补统计、回归
- 每项写清怎么查、通过标准、不处理会怎样（附测试库实测数字）
- 配合站上的只读预检 SQL 使用，每个业务库各跑一次
下一步
价格以对应页面当前标价为准。
出处（最后核对 2026-11-04）
- PostgreSQL 源码 REL_18_STABLE：src/backend/libpq/auth.c（auth_failed）
- PostgreSQL 源码 REL_18_STABLE：src/backend/libpq/crypt.c
- PostgreSQL 18 文档 20.5：Password Authentication
- PostgreSQL 14 文档 20.3：password_encryption（默认 scram-sha-256）
- PostgreSQL 18 文档 20.16：Authentication Problems
本页摘录并解读上面列出的官方文档，不是官方页面；官方文档更新后以官方为准。本页内容都来自官方文档，没有我们自己的测试结果。