FATAL: Password authentication failed

[supabase-search[bot]]

This is a copy of a troubleshooting article on Supabase's docs site. It may be missing some details from the original. View the original article.

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.

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.