FATAL: Password authentication failed

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:

• Direct connections and the dedicated pooler use postgres.
• Shared pooler connections use 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#

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?#

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#

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.

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.

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.

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.