PostgreSQL · error reference
PostgreSQL: password authentication failed for user
FATAL: password authentication failed for user "app"
PostgreSQL rejected the login. The client only ever sees this one line, whatever the reason; the server log says which of five things actually went wrong.
What the database is telling you
SQLSTATE 28P01 (invalid_password). The server found a pg_hba.conf line for this connection that asks for a password (scram-sha-256 or md5), checked the one the client sent, and refused it. On purpose, the client gets no detail: telling a stranger whether the user exists would help them guess. The detail goes to the server log as a DETAIL line next to the FATAL.
Why it shows up in a migration
Migrations connect from somewhere new — a container, a CI runner, a hosted service — with credentials copied into a connection string. That is where passwords pick up a trailing newline, lose characters to URL parsing, or end up pointed at a different server that has a user of the same name.
Common causes
- The password is wrong, or was copied with a trailing space or newline.
- The password contains @ : / ? # or % and was pasted raw into a postgresql:// URL, so the URL parser cut it short. Each must be percent-encoded (@ is %40).
- The role's password expired: VALID UNTIL is in the past. PostgreSQL reports an expired password with this same message.
- The role has no password at all (it was created for peer or trust login), which the log reports as "User has no password assigned".
- You are reaching a different server than you think — a local Postgres on 5432 instead of the Docker one, or a replica — where the same user name has a different password.
How to fix it
- 1
Read the server log first. The DETAIL line under the FATAL names the real reason and the pg_hba.conf line that matched.
-- in the server log, next to the FATAL: -- DETAIL: Password does not match for user "app". -- Connection matched pg_hba.conf line 99: "host all all 0.0.0.0/0 scram-sha-256"
- 2
Check whether the role exists, can log in, and whether its password has expired.
SELECT rolname, rolcanlogin, rolvaliduntil FROM pg_roles WHERE rolname = 'app';
- 3
Set a new password (and clear an expiry) as a superuser or the role's owner.
ALTER ROLE app WITH LOGIN PASSWORD 'new-password' VALID UNTIL 'infinity';
- 4
Percent-encode special characters when the password sits inside a URL, or pass it as a separate parameter instead.
-- p@ss:word becomes p%40ss%3Aword postgresql://app:p%40ss%3Aword@db.example.com:5432/shop
- 5
Prove which server you are on: connect with psql using the same host and port, then check the address it reports.
SELECT inet_server_addr(), inet_server_port(), current_database();
What DBShifts does about it
Connection diagnosis reads a failed connect and answers with a fixed cause — here "Authentication failed", with the hint to check the user, the password and whether this user may connect from DBShifts' address — rather than echoing the driver's message, which can carry the user name or the SQL. Passwords are stored encrypted, and the connection URL is built with the user name and password percent-encoded, so @, : and / in a password survive.
Connection diagnosis
Connecting a database?
Add the database to DBShifts and the connection is tested on the spot. If it fails, you get which of these errors it is and what to change — not the driver's raw message. Once it connects, browse it, migrate it, or let an AI agent read it through the gateway with sensitive columns masked.