mirror of
https://github.com/supabase/supabase.git
synced 2026-10-06 09:55:06 +03:00
Kostas Botsasandcoderabbitai[bot]
e1e16d4a18
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs ## Additional context Explicitly mention custom roles in the troubleshooting guide for password authentication failure <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added troubleshooting guidance for using custom PostgreSQL roles with direct connections, dedicated pooling, and shared pooling. - Documented temporary authentication failures that may occur after resetting a custom role’s password when using shared pooling. - Added guidance to verify the password directly and retry shared-pooler connections with bounded retries. - Added a link to password-rotation documentation for further details. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
46 lines
3.6 KiB
Plaintext
46 lines
3.6 KiB
Plaintext
---
|
|
title = "FATAL: Password authentication failed"
|
|
date_created = "2026-09-02T00:00:00+00:00"
|
|
topics = [ "database", "supavisor" ]
|
|
keywords = [ "password", "authentication", "credentials", "fail2ban" ]
|
|
[[errors]]
|
|
message = "FATAL: password authentication failed for user"
|
|
---
|
|
|
|
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).
|