# 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](/docs/guides/troubleshooting/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](https://en.wikipedia.org/wiki/Percent-encoding) 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](/docs/guides/troubleshooting/how-do-i-reset-my-supabase-database-password-oTs5sB) in [Database settings](/dashboard/project/_/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](/docs/guides/troubleshooting/supavisor-error-password-authentication-failed-after-password-rotation).

## 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](/docs/guides/troubleshooting/supavisor-error-password-authentication-failed-after-password-rotation).

## 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](/docs/guides/troubleshooting/error-connection-refused-when-trying-to-connect-to-supabase-database-hwG0Dr) 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](/docs/guides/troubleshooting/supavisor-error-circuit-breaker-open-after-password-rotation-0fdb72).