How to fix FATAL: role "username" does not exist in PostgreSQL

PostgreSQLINTERMEDIATEHIGHUpdated Dec 26, 2025· 211 views

This error occurs when PostgreSQL attempts to authenticate a user role that hasn't been created in the database. The role must be explicitly created before it can be used for connections.

Quick fix

Fixes FATAL: role "username" does not exist

# On Linux with systemd
sudo systemctl status postgresql

# On macOS with Homebrew
brew services list | grep postgres

# Check if PostgreSQL is listening
sudo lsof -i :5432
  1. Verify PostgreSQL is running and accessible
  2. Connect as the default postgres superuser
  3. Create the missing role with LOGIN privilege
  4. Grant necessary database privileges
postgresql — error
# On Linux with systemd
sudo systemctl status postgresql
# On macOS with Homebrew
brew services list | grep postgres
# Check if PostgreSQL is listening
sudo lsof -i :5432
FATAL: role "username" does not exist

What this error means

In PostgreSQL, a "role" is the core authentication object. When you try to connect to PostgreSQL using a username that doesn't exist as a role in the database, PostgreSQL rejects the connection with this fatal error. Unlike password authentication failures, this error means the user itself is missing from the database entirely. PostgreSQL will attempt to use your current system username if you don't specify one, which is why this error commonly occurs when the system user doesn't match a PostgreSQL role.

Typical symptoms

  • Connection attempts fail with "FATAL: role "username" does not exist"
  • psql commands fail when connecting to the database
  • Application connection strings fail with role authentication errors
  • Docker PostgreSQL containers fail to initialize with custom users
  • Error occurs even though the password might be correct

Common causes

  1. The role was never created in PostgreSQL during setup
  2. The PostgreSQL service was reinstalled or reset, clearing previous roles
  3. Connection string uses a different username than the created roles
  4. Custom roles were not created when initializing a PostgreSQL container
  5. Case sensitivity mismatch between the requested role and created roles
  6. Connecting with system username that doesn't match any PostgreSQL role

How to fix "FATAL: role "username" does not exist"

1Verify PostgreSQL is running and accessible

First, ensure PostgreSQL is actually running on your system. If the service is down, you won't be able to connect to create roles.

bash
# On Linux with systemd
sudo systemctl status postgresql

# On macOS with Homebrew
brew services list | grep postgres

# Check if PostgreSQL is listening
sudo lsof -i :5432

If PostgreSQL is not running, start it:

bash
# Linux
sudo systemctl start postgresql

# macOS
brew services start postgresql
2Connect as the default postgres superuser

Use the default "postgres" superuser to create the missing role. This superuser is created during PostgreSQL installation.

bash
# Connect as the postgres user (may require sudo)
sudo -u postgres psql

# Or if postgres system user doesn't exist, connect directly with -h 127.0.0.1
psql -U postgres -h 127.0.0.1

If you get an error here, the postgres role itself may be missing (see Advanced Notes).

3Create the missing role with LOGIN privilege

Once connected to psql as a superuser, create the role using the CREATE ROLE command. The WITH LOGIN clause is essential—without it, the role exists but cannot be used for connections.

sql
-- Create a role that can log in (equivalent to a "user")
CREATE ROLE username WITH LOGIN PASSWORD 'your_password';

-- Or if you don't want password authentication initially
CREATE ROLE username WITH LOGIN;

The role name is case-sensitive by default in PostgreSQL. Use quotes if you need uppercase letters:

sql
CREATE ROLE "MyUser" WITH LOGIN PASSWORD 'password';
4Grant necessary database privileges

Create a database if needed and grant the role permission to access it:

sql
-- Create a database owned by the role
CREATE DATABASE myapp OWNER username;

-- Or grant permissions to an existing database
GRANT CONNECT ON DATABASE myapp TO username;
GRANT USAGE ON SCHEMA public TO username;
GRANT CREATE ON SCHEMA public TO username;

Without these grants, the role can connect to PostgreSQL but cannot access databases or tables.

5Test the connection with the new role

Exit the superuser session and test connecting as the newly created role:

bash
# Exit psql
\q

# Connect as the new user
psql -U username -d myapp -h 127.0.0.1

Use -h 127.0.0.1 to force TCP connection (bypasses peer authentication and uses password authentication). Without it, PostgreSQL uses peer authentication by default on local connections, which requires your system username to match the role name.

6Update your application connection string

Make sure your application uses the correct role credentials:

bash
# Database URL format
postgresql://username:password@localhost:5432/myapp

# Node.js with pg
const client = new Client({
  user: 'username',
  password: 'your_password',
  host: 'localhost',
  port: 5432,
  database: 'myapp',
});

# Python with psycopg2
conn = psycopg2.connect(
  dbname="myapp",
  user="username",
  password="your_password",
  host="localhost",
  port="5432"
)

Verify the username and database name match exactly what you created in PostgreSQL.

Advanced notes

If the "postgres" role itself doesn't exist, you'll need superuser system access. On most systems, PostgreSQL installation creates a system user named "postgres" and a corresponding database role. If this is missing, you may need to reinstall PostgreSQL or recover using recovery mode. For Docker, always set POSTGRES_USER and POSTGRES_PASSWORD environment variables during container initialization. Peer authentication on Linux requires your system username to match the PostgreSQL role name when connecting locally—use -h 127.0.0.1 to bypass this and use password authentication instead. Role names are case-sensitive unless quoted, and case-insensitive matching does not work even with lowercase specifications. For production systems, always use strong passwords and follow the principle of least privilege when granting role permissions.

Frequently asked questions

What does "FATAL: role "username" does not exist" mean?
In PostgreSQL, a "role" is the core authentication object. When you try to connect to PostgreSQL using a username that doesn't exist as a role in the database, PostgreSQL rejects the connection with this fatal error. Unlike password authentication failures, this error means the user itself is missing from the database entirely.
How do I fix "FATAL: role "username" does not exist"?
This error occurs when PostgreSQL attempts to authenticate a user role that hasn't been created in the database. The role must be explicitly created before it can be used for connections.
What causes "FATAL: role "username" does not exist"?
The role was never created in PostgreSQL during setup The PostgreSQL service was reinstalled or reset, clearing previous roles Connection string uses a different username than the created roles
Is the "FATAL: role "username" does not exist" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading