PostgreSQL “password authentication failed for user” means an authentication attempt did not satisfy the server’s selected rule. It is different from “no pg_hba.conf entry,” “role does not exist,” or the server refusing a TCP connection.
This guide is for PostgreSQL password authentication failed in its stated software or device context. Capture the exact message and the operation that fails; the same keyword may have different meanings in another application. A reliable diagnosis identifies an observable difference, not just a plausible cause.
Recognize the symptoms
- A database client connects to the server but receives FATAL: password authentication failed for user.
- A deployed app fails after rotating secrets while manual local psql works.
- Only one host, role or SSL connection mode fails.
Record the software version, device or server role, first failure time and any update or configuration change immediately before the incident. Compare whether the symptom affects one file, one user, one device or the entire service. These observations guide the safest first test.
Before making changes
Keep a restorable copy of important files, settings and credentials wherever the procedure might modify them. Use the original account, workflow and network for comparison. Perform one controlled change at a time, record the outcome, and undo changes that do not affect the failure.
If the action can create payments, data writes, account changes or destructive storage activity, do not retry it automatically. Confirm whether the previous operation already succeeded. Managed devices, production databases and service infrastructure require the owner’s authorization.
Step-by-Step Troubleshooting
Choose Beginner for reversible checks; Advanced covers evidence-based inspection, bounded changes and verification.
Capture the full redacted error
Record exact role, host, port, database and timestamp. Do not share connection strings if they contain passwords or query parameters with secrets.
Confirm the target database instance
Check whether the hostname or service alias points to the intended PostgreSQL server and port. A staging app pointing to production can produce misleading password failures.
Compare role and secret source
Inspect the application secret configuration and any recent rotation without printing credentials. Check whether containers or services need a documented restart/reload after a secret update.
Test through an authorized client
Use a trusted psql or application health check to connect as the intended role. Never switch to the postgres superuser merely to get around failed least-privilege credentials.
Read server authentication logs
Correlate the client source address and PostgreSQL FATAL event to the matching server. Verify whether the failure is a bad password, non-existent role or no matching pg_hba rule.
SHOW hba_file;SHOW password_encryption;SELECT type, database, user_name, address, auth_method, error FROM pg_hba_file_rules;Inspect effective pg_hba.conf rule order
Authentication selects the first matching connection-type, database, role and address line. Review pg_hba_file_rules when available and check the actual IPv4/IPv6 source.
Verify password-hash and client support
On supported PostgreSQL versions, SCRAM-SHA-256 is the modern default authentication direction. Check client compatibility instead of falling back to insecure trust or broad address access.
Rotate only the affected credential safely
With authorization, rotate the role secret using your secret manager, update the application and test the intended path. Confirm grants stay minimal and rollback is planned for coordinated deployments.
Diagnosis: identify the layer that is actually failing
Start with the evidence collected by the Beginner or Advanced tab, then compare the patterns below. A match is a working hypothesis; it is not proof until the original operation succeeds after a targeted, reversible change.
| Observed pattern | Evidence to inspect | Most useful next step |
|---|---|---|
| Local socket works, remote fails | Host, port and first matching pg_hba rule | Compare effective authentication methods. |
| After credential rotation | Secret version and app restart/reload | Ensure clients use the new authorized secret. |
| One app user fails | Effective role name and connection URI | Check role existence, spelling and source of secret. |
Common root causes to rule in or out
- The application loads an old or incorrect password from environment variables or secret storage.
- The connection targets an unexpected PostgreSQL instance, port, role or database.
- The effective pg_hba.conf method and encryption/protocol configuration differ between environments.
A recent change establishes a useful timeline but not causation on its own. Look for a repeatable relationship: does the failure follow a particular account, release, host, storage volume or workload? Compare an unaffected example under nearly identical conditions before choosing any broad repair.
What each result means
When the same problem reproduces on multiple independent devices or clients, focus on shared account, service or infrastructure conditions. When it follows one client, check its runtime, policies and local state. When only one particular operation fails, inspect that workload before reinstalling unrelated components.
If a command or diagnostic produces a different result than the article describes, stop and interpret that actual output. Examples are not meant to be executed blindly: identifiers, installation paths, network ports and supported options can vary by version and permissions.
How to verify the repair
Return to the exact action that produced PostgreSQL password authentication failed. Repeat the safe test under the original account, environment and input conditions. An error disappearing after one reload is not enough if the underlying service still produces failures under normal use.
- Test from the originally failing host/network.
- Confirm role permissions and selected authentication method.
- Review logs for repeat failures after secret rotation.
Confirm that the adjacent feature still works and that the protective controls, data and settings kept during diagnosis remain intact. Record the exact effective change and keep the rollback instructions; a completed checklist is a tracking aid, not a guarantee that all failure conditions are gone.
Solution Checklist
If the error remains: rollback and escalation
If rotation blocks dependent services, use the approved secret-management rollback plan and coordinate deployments. Do not leave a temporary trust authentication rule in place.
Provide support with the redacted exact message, timestamps and timezone, version, environment, scope, relevant log excerpts and tests attempted. Do not include passwords, session cookies, license keys, complete private URLs or other secrets in public tickets.
How to prevent it from returning
- Use a secret manager with documented rotation procedures.
- Keep pg_hba.conf rules scoped and version controlled.
- Log redacted authentication failures with host/role context.
Maintain a short incident note that distinguishes the confirmed cause from hypotheses that were tested and rejected. Update the note when a product release or platform policy changes the troubleshooting sequence.
Frequently asked questions
Is this always an incorrect password?
Not always. Connection targeting, role name, authentication method or secret distribution may be wrong.
Will using trust fix the problem?
It bypasses password checks and creates a security risk; diagnose the matching rule and legitimate credentials instead.
Further reading: official documentation
Editorial note: vendor interfaces, error-code behavior and supported versions may change. Confirm the relevant product documentation before deploying a change to a production or managed system. This draft does not claim that every remedy was tested on the reader’s environment.