Recommended Free Tools
This error means PostgreSQL selected an ident authentication rule, but the operating-system identity it checked was not authorized as the requested database role. Supplying a password does not change that check. Find the first matching rule in pg_hba.conf, then choose a fix that matches how you intend the connection to authenticate.
Why PostgreSQL reports an ident authentication failure
PostgreSQL uses pg_hba.conf to select how a connection is authenticated. The first rule matching the connection type, client address where applicable, requested database, and PostgreSQL user is used. If that rule rejects the login, PostgreSQL does not try a later rule as a fallback. See the PostgreSQL 18 documentation for pg_hba.conf.
ident checks an operating-system identity rather than a database password. For a TCP/IP connection it asks an ident service on the client machine for the OS username. For a Unix-domain socket, an HBA rule that says ident uses peer authentication instead: PostgreSQL obtains the local OS username from the operating system. A password supplied with -W or another client option will not make either method behave like password authentication.
Check whether the connection uses a socket or TCP/IP
The transport determines which HBA rules can match. On Unix-like systems, psql without a host commonly uses a Unix-domain socket, depending on client settings and environment. Specifying -h hostname normally requests TCP/IP. A socket connection matches local records; TCP/IP matches host records. Do not assume localhost and a socket use the same rule.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors#1 Best Overall
- Review the
psqlcommand and connection parameters, including any environment or service configuration that supplies a host. - Check the connection details and server log if the error output does not make the transport clear.
- Keep the transport the same when testing a configuration change, so you can verify the intended rule.
Find the active HBA rule and configuration files
Ask the database administrator or inspect the server configuration to find the active files. The defaults are in the database cluster’s data directory, but hba_file and ident_file can point elsewhere; editing a guessed path may have no effect. PostgreSQL documents these locations in its file-location settings.
- Open the active
pg_hba.conf. - Starting at the top, locate the first entry matching the connection type, client address if applicable, database, and requested PostgreSQL role.
- Check the authentication method and any map name on that entry. Later password-based entries do not take over if this one rejects the connection.
- Review the server log for details. The
pg_hba_file_rulesview can help identify HBA parsing problems. Thepg_ident_file_mappingsview can show loaded ident-map rules; a non-nullerrorvalue indicates an issue with the corresponding line. See the HBA rules view and ident mappings view.
Choose an authentication method that fits the connection
| Method | Connection type | Identity checked | Key consideration |
|---|---|---|---|
| Peer | Local Unix-domain socket | Username reported by the local operating system | Use when the OS account is intended to access the corresponding database role; an optional map can relate different names. |
| Ident | TCP/IP | Username reported by an ident service on the client | Requires trusting and controlling the client machine and its ident service; an optional map can relate different names. |
Password authentication, such as scram-sha-256 |
Local socket or TCP/IP, when configured by a matching HBA rule | Password for the PostgreSQL role | Use a client that supports SCRAM and a role with a usable password; choose a rule with appropriately limited scope. |
PostgreSQL describes peer as a local authentication method and ident as a method for TCP/IP; its overview generally recommends password authentication for remote connections. Read the official documentation on authentication methods.
Rank #2
For local administrative access
Peer authentication can suit local administration when the operating-system account and PostgreSQL role are intended to correspond. Run psql under the appropriate OS account, or configure a limited username map if the names intentionally differ. Peer is not a password check.
For a TCP/IP connection that should use ident
Confirm the client machine runs a functioning ident service and that it reports the expected OS username. Ident relies on trusting the client machine, so PostgreSQL considers it appropriate only for a closed network where client machines are tightly controlled.
If the reported OS name legitimately differs from the PostgreSQL role, configure a narrowly scoped entry in pg_ident.conf, then reference its map name on the intended HBA rule with map=mapname. A mapping authorizes the mapped OS user to connect as the specified database user, so avoid broad mappings. See PostgreSQL’s username map documentation.
For password authentication
Use a matching HBA rule with scram-sha-256 if password authentication is the intended model. Confirm the PostgreSQL role exists, has a usable password, and the client supports SCRAM. Check the rule order: the intended rule must be the first match. PostgreSQL marks MD5-encrypted passwords as deprecated, and clear-text password authentication is unsuitable on untrusted networks.
For example, this pattern covers a TCP/IP client connecting over IPv4 loopback; it is not a universal replacement for every installation:
host mydb myuser 127.0.0.1/32 scram-sha-256Replace the database, role, address, and position with values appropriate to the installation, and review the rule’s access scope. A socket connection needs a matching local rule instead of this host example.
Reload the configuration and verify the result
After changing pg_hba.conf or pg_ident.conf, reload the server configuration on most systems. Use the service manager appropriate to the installation, pg_ctl reload, SQL SELECT pg_reload_conf();, or SIGHUP. PostgreSQL documents that on Windows, HBA changes apply immediately to subsequent new connections. Check the server log for parse or authentication errors, then retry using the same transport and connection parameters. The official HBA documentation and username-map documentation describe configuration behavior.
Avoid common troubleshooting mistakes
- Assuming a supplied password will be checked: the selected HBA method controls authentication. An ident or peer rule will not switch to password verification because you passed a password.
- Expecting a later rule to be tried: PostgreSQL selects the first matching rule and does not fall through when authentication fails.
- Treating ident and peer as identical: TCP/IP ident consults an ident service on the client; local peer gets the username from local OS facilities.
- Renaming a database role unnecessarily: a deliberate, narrowly scoped
pg_ident.confmapping can relate different OS and PostgreSQL usernames. - Editing a file without checking its path or reloading: verify the active configuration file, reload where required, and look for errors in the server log.
- Using
trustas a harmless shortcut: a matching trust rule lets anyone able to connect log in as any covered database user without authentication. Do not use it as a broad fix.
The error text alone cannot tell you which HBA entry matched or which method is appropriate for your server. The active rule, connection transport, configuration paths, and server log determine the correct fix.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
