How to Fix ‘psql: FATAL: role does not exist’ PostgreSQL Error

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: FATAL: role "yourname" does not exist confuses people because they never asked to connect as “yourname”. PostgreSQL defaults the database username to your operating system username, and unless a matching role exists, the connection fails.

Why It Happens

When you run psql with no arguments, PostgreSQL fills in three defaults:

• Username — your OS username
• Database — the same as the username
• Host — the local Unix socket

So on a machine where you log in as alice, plain psql means “connect to database alice as role alice“. A fresh PostgreSQL install creates only the postgres superuser role, so that connection fails immediately.

Fix 1: Connect as the postgres Role

The quickest check — confirm the server is running and reachable.

# Linux: the postgres OS user maps to the postgres role
sudo -u postgres psql

# macOS with Homebrew: your own user is usually the superuser
psql postgres

# Explicit form that works anywhere
psql -U postgres -d postgres -h localhost

If this connects, the server is fine and you only need to create your role.

Fix 2: Create a Role That Matches Your Username

This is the proper fix for local development, because it makes bare psql work the way you expected.

# From the shell
sudo -u postgres createuser --interactive --pwprompt

# It will ask:
#   Enter name of role to add: alice
#   Enter password for new role: ****
#   Shall the new role be a superuser? (y/n) n
#   Shall the new role be allowed to create databases? (y/n) y
#   Shall the new role be allowed to create more new roles? (y/n) n

Or in SQL, which is clearer about what you are granting:

sudo -u postgres psql

CREATE ROLE alice WITH LOGIN PASSWORD 'a-strong-password';
ALTER ROLE alice CREATEDB;
\q

LOGIN is essential and easy to miss. CREATE ROLE alice; without it creates a group role that cannot connect, and you get a different confusing error.

Fix 3: The Matching Database Also Has to Exist

Creating the role often produces the next error, which people mistake for the same problem.

psql
# psql: FATAL: database "alice" does not exist

Create it, or always name a database explicitly.

createdb alice

# Or specify one every time
psql -d postgres

Fix 4: Specify the User Explicitly

If you do not want a role matching your OS username, pass the one you want.

psql -U myapp -d myapp_development -h localhost

# Or set it in the environment for the session
export PGUSER=myapp
export PGDATABASE=myapp_development
export PGHOST=localhost
psql

Note that -U over a Unix socket may still fail depending on your authentication configuration — see the peer section below.

Fix 5: Docker and docker-compose

Inside a container, the role is whatever POSTGRES_USER specified when the volume was first initialised.

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp_development
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

# Connect from the host
psql -U myapp -d myapp_development -h localhost -p 5432

# Connect inside the container
docker compose exec db psql -U myapp -d myapp_development

The trap: those environment variables only take effect when the data directory is empty. If you change POSTGRES_USER on an existing volume, nothing happens and you keep getting the old role. Recreate the volume to apply it.

# Destroys the database contents — make sure that is acceptable
docker compose down -v
docker compose up -d

Understanding peer Authentication

On Linux, local socket connections usually use peer authentication, which requires the database role name to match the OS username exactly. This is why sudo -u postgres psql works while psql -U postgres as your own user does not.

# Find the config file
sudo -u postgres psql -c 'SHOW hba_file;'
# e.g. /etc/postgresql/17/main/pg_hba.conf

# pg_hba.conf
# TYPE  DATABASE  USER  ADDRESS       METHOD

# peer: OS username must equal the role name
local   all       all                 peer

# scram-sha-256: password authentication, any username
local   all       all                 scram-sha-256
host    all       all   127.0.0.1/32  scram-sha-256

Switching the local line to scram-sha-256 lets -U work over the socket with a password. Reload afterwards — the file is not re-read automatically.

sudo systemctl reload postgresql
# or
sudo -u postgres psql -c 'SELECT pg_reload_conf();'

Do not change peer to trust. That allows any local user to connect as any role with no password, including superusers.

macOS Specifics

Homebrew’s PostgreSQL creates a superuser matching your macOS username and a database of the same name, so bare psql usually works. Postgres.app behaves similarly. If you see this error on macOS, the usual causes are that the service is not running or that an older installation is shadowing the newer one.

brew services list
brew services start postgresql@17

# Check which psql is first on PATH
which psql
psql --version

Diagnosing Systematically

# 1. Is the server running?
pg_isready
# /tmp:5432 - accepting connections

# 2. Which roles exist?
sudo -u postgres psql -c '\du'

# 3. Which databases exist?
sudo -u postgres psql -c '\l'

# 4. What is psql defaulting to?
psql -d postgres -c 'SELECT current_user, current_database();'

# 5. What is your OS username?
whoami

Comparing steps 2 and 5 answers the question immediately in almost every case.

Related Errors

Frequently Asked Questions

Q: What is the difference between a role and a user?
A: None, functionally. CREATE USER is shorthand for CREATE ROLE ... WITH LOGIN. PostgreSQL uses “role” for both users and groups.

Q: Should I make my development role a superuser?
A: For a purely local database, it is convenient. Never do it for anything reachable by others, and never for a role your application connects with.

Q: Why does it work in Docker but not on the host?
A: Different servers. The container has its own PostgreSQL with its own roles. Connecting from the host requires the port mapping and the container’s credentials.

Q: My app connects fine but psql does not. Why?
A: The app has a connection string with an explicit username, password, and host. Bare psql uses defaults. Read the role name out of your app’s connection string and pass it with -U.

Q: How do I change a role’s password?
A: ALTER ROLE alice WITH PASSWORD 'new-password'; as a superuser.

Conclusion

This error means PostgreSQL tried to authenticate a role that does not exist — almost always because psql defaulted to your OS username. Check which roles exist with \du, compare against whoami, then either create a matching role with LOGIN or pass -U explicitly. On Linux, remember that peer authentication requires the names to match over local sockets; in Docker, remember that POSTGRES_USER only applies when the volume is first created.