"password authentication failed": check the string before rotating

Not specified by the original author.

TL;DR

For "FATAL: password authentication failed for user "[role]"": the password actually was reset (teammate rotated it, branch was recreated). 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.

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

Steps

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).
4. - 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.

When to use

You are seeing this: FATAL: password authentication failed for user "[role]". Use this skill when you run into ""password authentication failed": check the string before rotating".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

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.

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.