Skip to content

inchTodd/db-error-troubleshooting-skills / skills/pg-password-authentication-failed

pg-password-authentication-failed

Verified

排查 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)。

关键事实

项内容
SQLSTATE28P01(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-256pg_hba 写 md5pg_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,需要升级驱动。

给 agent 的使用守则

  • 先让用户贴出完整报错和执行的命令,按上面的顺序做只读检查,再给修改建议。
  • 不要求用户提供密码、连接串里的凭证或生产数据;需要时让用户自己在本机执行命令并贴结果(可先打码)。
  • 改配置(pg_hba.conf、my.cnf、授权语句)前先说明影响并让用户确认;本 skill 不承诺任何修复效果。

来源

完整图文版和相关报错:https://surinch.com/tools/postgresql-error/password-authentication-failed

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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall