FATAL: Password authentication failed
Last edited: 10/14/2026
FATAL: Password authentication failed 错误意味着 Postgres 拒绝了你的凭证。先检查用户名再检查密码，因为用户名出错的情况更常见。
🌐 A FATAL: Password authentication failed error means Postgres rejected your credentials. Check the username before the password, because the username is the more common mistake.
先检查一下用户名 #
🌐 Check the username first
用户名取决于你如何连接：
🌐 The username depends on how you connect:
- 直接连接和专用的池化器使用
postgres。 - 共享池连接使用
postgres.[PROJECT-REF]。
提供错误的用户名通常会显示未找到租户或用户，而不是这个错误，但一个有效的用户名配错密码就会出现这个情况。
🌐 Supplying the wrong one usually produces Tenant or user not found rather than this error, but a valid username with the wrong password lands here.
检查密码 #
🌐 Check the password
当保留字符出现在连接字符串中时，密码中的这些字符必须进行 百分号编码。这包括 &、#、? 以及空格等。密码在图形界面字段中可以使用，但仅因为这个原因，在 URI 中可能就会失败。
🌐 Reserved characters in a password have to be percent-encoded when they appear in a connection string. This covers &, #, ?, and spaces, among others. A password that works in a GUI field can fail in a URI for this reason alone.
🌐 If you don't have the password, reset it in Database settings.
换密码了吗？ #
🌐 Rotated the password?
如果你是通过共享连接池连接，而且这问题是在重置角色密码后才出现的——用户名和密码本身是正确的——请参阅 Supavisor 错误：“密码验证失败”，在旋转数据库密码后。
🌐 If you're connecting through the shared pooler and this started right after resetting the role's password — with the username and password otherwise correct — see Supavisor error: "password authentication failed" after rotating database password.
使用自定义角色 #
🌐 Using a custom role
支持带有 LOGIN 的自定义 Postgres 角色。它们可以在直接连接、专用连接池以及共享 Supavisor 连接池上使用。你不需要把角色单独在连接池中注册。连接池会按需从 Postgres 读取角色的凭证，所以只需要在数据库中创建角色就行了。
🌐 Custom Postgres roles with LOGIN are supported. They work on direct connections, the dedicated pooler, and the shared Supavisor pooler. You do not register a role with the pooler as a separate step. The pooler reads the role's credentials from Postgres on demand, so creating the role in the database is all that is needed.
如果你在使用共享连接池（Supavisor）时重置了自定义角色的密码，即使新密码正确，池化连接仍可能会以 FATAL: password authentication failed（SQLSTATE 28P01）失败。连接池可能会短暂使用缓存的凭据。可以用直接连接确认新密码，然后通过带有有限重试的 Supavisor 再试一次。直接连接和专用连接池不受这种缓存行为影响。
🌐 If you reset the password of a custom role while using the shared pooler (Supavisor), a pooled connection can still fail with FATAL: password authentication failed (SQLSTATE 28P01) even when the new password is correct. The pooler may still use cached credentials briefly. Confirm the new password with a direct connection, then retry through Supavisor with bounded retries. Direct connections and the dedicated pooler are not affected by this cache behavior.
要了解完整的轮换流程，请参见 Supavisor 错误：“密码验证失败”，在轮换数据库密码后。
🌐 For the full rotation flow, see Supavisor error: "password authentication failed" after rotating database password.
反复失败会导致不同的错误 #
🌐 Repeated failures cause a different error
同一个地址重复验证失败会导致该地址被封禁。一旦被封禁，连接就不会再出现这个错误，而是会改为出现连接被拒绝的错误。
🌐 Repeated authentication failures from the same address get that address banned. Once banned, connections stop failing with this error and start failing with connection refused instead.
如果你在测试凭证时错误从“身份验证失败”变成了“连接被拒绝”，说明你是被封了而不是被锁了。那个页面有解封的步骤。
🌐 If your error changes from authentication failed to connection refused while you're testing credentials, you're banned rather than locked out. That page has the unban procedure.
这适用于直接连接和专用连接池。共享连接池有自己处理重复失败的机制：你不会看到被禁止的 IP，而是会看到 FATAL: Circuit breaker open。查看 Supavisor 错误：“密码旋转后断路器打开”。
🌐 This applies to direct connections and the dedicated pooler. The shared pooler has its own separate mechanism for repeated failures: instead of a banned IP, you'll see FATAL: Circuit breaker open. See Supavisor error: "Circuit breaker open" after password rotation.