About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
FATAL: Peer authentication failed for user "app_user" means PostgreSQL applied a rule that uses the peer method and the check failed. Peer compares the Linux user name of the process that is connecting with the database user name it asked for. If they differ, the connection is refused. Connect as the matching Linux user, connect over TCP so a different rule applies, or add a user name map.
What the error means
The PostgreSQL manual says peer authentication "works by obtaining the client's operating system user name from the kernel and using it as the allowed database user name (with optional user name mapping). This method is only supported on local connections." In pg_hba.conf, the peer method entry says it will "Obtain the client's operating system user name from the operating system and check if it matches the requested database user name."
"Local" here means a Unix-domain socket. The local record type "matches connection attempts using Unix-domain sockets". The client library chooses a socket when no host is given: libpq says "The default behavior when host is not specified, or is empty, is to connect to a Unix-domain socket". It also says the user parameter "Defaults to be the same as the operating system name of the user running the application."
The server reads pg_hba.conf top to bottom and uses the first matching record: "The first record with a matching connection type, client address, requested database, and user name is used to perform authentication. There is no “fall-through” or “backup”: if one record is chosen and the authentication fails, subsequent records are not considered. If no record matches, access is denied." So a later scram-sha-256 rule for the same user does not rescue a socket connection that matched an earlier peer line.
The message text comes from PostgreSQL's source code (file src/backend/libpq/auth.c, release REL_17_12), because the manual does not print it. The source has the format Peer authentication failed for user "%s", where the %s part varies and is the database user name you asked for. The manual says peer authentication is "only available on operating systems providing the getpeereid() function, the SO_PEERCRED socket parameter, or similar mechanisms", which it says includes Linux, most flavors of BSD including macOS, and Solaris.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
Linux user differs from the database user in -U |
psql -U app_user run as another Linux user fails |
whoami prints a name other than the one after -U |
| Application service runs as one Linux user but connects as another database role | Works from a shell as the right user, fails from the service | The service unit or process owner differs from the database user in the connection string |
A local ... peer line matches before the rule you meant to use |
You expected a password prompt and never got one | pg_hba_file_rules shows a local row with peer earlier than your rule |
| Connection went over the socket when you meant TCP | No -h or an empty host in the connection string |
psql without -h uses the socket |
| Map missing or misnamed | peer map=name rule present but fails for a mapped user |
pg_ident_file_mappings lacks the pair or shows an error on that line |
Prove the cause before changing anything
All of these are read-only.
1. Who are you on Linux, and who did you ask to be in the database?
whoami
psql -U app_user -d appdb
If whoami prints deploy and the database user is app_user, the two names differ, which fails the peer check.
2. See the rules the server loaded. pg_hba_file_rules gives a row for each non-empty, non-comment line of pg_hba.conf, with "annotations indicating whether the rule could be applied successfully". By default it "can be read only by superusers", so use a superuser session (for example sudo -u postgres psql on a typical Linux server).
SELECT rule_number, line_number, type, database, user_name, address, auth_method, options, error
FROM pg_hba_file_rules;
Look for local rows. A row with auth_method peer that matches your database and user, with the lowest rule_number, is the one that applied. A non-null error marks a line that could not be processed. The view "reports on the current contents of the file, not on what was last loaded by the server", so a recent unreloaded edit shows here before it takes effect.
3. Find the file.
SHOW hba_file;
SHOW ident_file;
The manual says these name the configuration files for host-based authentication and user name mapping, and that both "can only be set at server start".
4. Read the server log. The manual says "The server log might contain more information about an authentication failure than is reported to the client."
Fix
Option 1: connect as the matching Linux user
For administrative access, run psql as the Linux user whose name equals the database user. The sudo manual says -u user runs the command "as a user other than the default target user (usually root)".
sudo -u postgres psql
This only changes how you connect, so it needs no save step and no back-out. For an application, run the service as the Linux user that matches the database role, or connect as the role that matches the service's user.
Option 2: connect over TCP
A connection with a host name or address goes by TCP and matches host records instead of local ones. The psql manual says -h gives the host name and that "If the value begins with a slash, it is used as the directory for the Unix-domain socket."
psql -h 127.0.0.1 -U app_user -d appdb
This works only if pg_hba.conf has a host record for that user, database and address that uses a password method such as scram-sha-256, and the role has a password. If no record matches, PostgreSQL refuses with a "no pg_hba.conf entry" error, covered under that exact title as "PostgreSQL "no pg_hba.conf entry for host": write the rule that matches, then reload". TCP also needs the server to listen on that address; see "PostgreSQL "Connection refused" on port 5432: listen_addresses, the service and the firewall".
Option 3: add a user name map
Use this when one Linux user must act as a different database role, such as a deployment account deploy that should log in as app_user. The manual describes the map file as lines of the form map-name system-username database-username, and says the map name "is an arbitrary name that will be used to refer to this mapping in pg_hba.conf".
First save both files, using the paths printed by SHOW hba_file; and SHOW ident_file;:
cp -p <hba_file> <hba_file>.2026-11-22
cp -p <ident_file> <ident_file>.2026-11-22
Risk: the next two edits change who may log in to the database as app_user over the local socket, and the reload that follows applies to the whole server. A wrong line can lock out every local login, including administrators. Keep a superuser session open in a second terminal while you do this, and place the new rule above any broader local ... peer line, because the first matching record wins.
Add two lines to the ident file. The manual says entries in a map mean "this operating system user is allowed to connect as this database user", so once the rule uses a map, only the pairs listed are allowed. The second line keeps the Linux user app_user, for example a service that runs under that name and works today, able to connect as app_user:
appmap deploy app_user
appmap app_user app_user
Add one rule to the HBA file, above the generic local rule:
local appdb app_user peer map=appmap
The peer page says map "Allows for mapping between system and database user names." Before reloading, check both files with the views the manual provides for this purpose, and look for non-null error values:
SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;
SELECT line_number, error FROM pg_ident_file_mappings WHERE error IS NOT NULL;
Both views read the files as they are now, so errors show before the reload. If either query returns rows, fix those lines first. Then reload. The manual says the files are read "when the main server process receives a SIGHUP signal" and that pg_reload_conf() is one way to send it:
SELECT pg_reload_conf();
Test as deploy, with psql -U app_user -d appdb.
To undo it: put both saved files back under their original names, check them, and reload:
cp -p <hba_file>.2026-11-22 <hba_file>
cp -p <ident_file>.2026-11-22 <ident_file>
Then, in a SQL session, check the restored file and reload. The error query should return no rows before you reload:
SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;
SELECT pg_reload_conf();
Example (illustrative): On db01, the Linux user deploy runs a migration script with psql -U app_user -d appdb. The server answers FATAL: Peer authentication failed for user "app_user". whoami prints deploy. pg_hba_file_rules shows rule 3, local all all peer, which matches. The team adds appmap deploy app_user and appmap app_user app_user to the ident file and local appdb app_user peer map=appmap above rule 3. Both error queries return no rows, pg_reload_conf() returns t, and the script now connects. The rule that applied compared user names, so the script's connection settings other than the user name did not need to change.
Confirm the fix
psql -U app_user -d appdbrun as the intended Linux user connects.- The rule you expected to apply has the lowest
rule_numberamong the rows that match inpg_hba_file_rules. - The error queries on
pg_hba_file_rulesandpg_ident_file_mappingsreturn no rows. - The server log shows no authentication failures from the service after the change.
What to watch afterwards
- Rule order. A new broad
localline placed above a narrow one changes who matches. - Keep the saved copies of both files until the change has run through a full cycle of the application.
- Services that connect over the socket under a new Linux user (after a redeploy or container change) fail again with the same message.
- Do not replace
peerwithtrustto get past the error. The manual saystrust"is usually not appropriate by itself on a multiuser machine".
Read next
Related articles you may want next.
- TroubleshootingPostgreSQL "password authentication failed for user": scram-sha-256, md5 and the stored passwordPostgreSQL 'password authentication failed for user'? The server log gives the real reason: wrong password, no role, expired, or md5 versus scram.Read article
- TroubleshootingPostgreSQL "no pg_hba.conf entry for host": write the rule that matches, then reloadPostgreSQL 'no pg_hba.conf entry for host'? Read the host, user, database and encryption in the message, add a matching record, check it, then reload.Read article
- TroubleshootingPostgreSQL "Connection refused" on port 5432: listen_addresses, the service and the firewallPostgreSQL 'Connection refused' on port 5432? Check the service, listen_addresses (default localhost) and the port, then the network path.Read article
Risks and limits
- These commands have not been run or lab-tested.
- Linux package builds may place the configuration files in different directories; use
SHOW hba_file;for the real path. - The manual does not show the exact layout of the client error line, so the message here is the server message only.
- A map allows a Linux user to act as a database user. Map only accounts you control, and prefer a narrow database and user in the rule.
Sources
- PostgreSQL 17 documentation: 20.9. Peer Authentication — PostgreSQL Global Development Group, no date shown (page shows version 17.12), accessed 22 November 2026
- PostgreSQL 17 documentation: 20.1. The pg_hba.conf File — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 20.2. User Name Maps — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 20.4. Trust Authentication — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 20.15. Authentication Problems — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 52.9. pg_hba_file_rules — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 32.1. Database Connection Control Functions — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 19.2. File Locations — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 9.28. System Administration Functions (pg_reload_conf) — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: psql — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- PostgreSQL 17 documentation: 52.10. pg_ident_file_mappings — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
- sudo manual — sudo.ws, no date shown, accessed 22 November 2026
- PostgreSQL source code, release REL_17_12: src/backend/libpq/auth.c — PostgreSQL Global Development Group, no date shown, accessed 22 November 2026
This article was originally published on .