"password authentication failed": check the string before rotating

Not specified by the original author.

"password authentication failed": diagnose and fix

Symptom

FATAL: password authentication failed for user "[role]".

Cause (check in order)

1. The connection string was hand-edited and the password got truncated or mangled; special characters in generated passwords must be URL-encoded in the string.
2. Wrong role for the string: the password belongs to a different role than the one in the URL.
3. The password actually was reset (teammate rotated it, branch was recreated).

Confirm

1. Re-copy the connection string fresh from the Console Connect modal and test with psql before touching app config.
2. If the fresh string works, the app's copy was stale or mangled; diff them.

Fix

• Use the Console-copied string verbatim; URL-encode special characters if you must embed the password manually.
• Store it in a secret manager, not pasted across chat and docs.
• If it really was rotated, update every deployment that uses it, then verify each.

Verify

psql connects with the exact string the app will use, then the app connects.

Neon's connection error docs (verified live 2026-09-26) list 'Password authentication failed for user' among the resolved connection errors; the connect docs describe copying the constructed string from the Connect modal per branch/compute/database/role.