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.
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.
First, ensure PostgreSQL is actually running on your system. If the service is down, you won't be able to connect to create roles.
# 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 :5432If PostgreSQL is not running, start it:
# Linux
sudo systemctl start postgresql
# macOS
brew services start postgresqlUse the default "postgres" superuser to create the missing role. This superuser is created during PostgreSQL installation.
# 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.1If you get an error here, the postgres role itself may be missing (see Advanced Notes).
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.
-- 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:
CREATE ROLE "MyUser" WITH LOGIN PASSWORD 'password';Create a database if needed and grant the role permission to access it:
-- 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.
Exit the superuser session and test connecting as the newly created role:
# Exit psql
\q
# Connect as the new user
psql -U username -d myapp -h 127.0.0.1Use -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.
Make sure your application uses the correct role credentials:
# 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.
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.
insufficient columns in unique constraint for partition key
How to fix "insufficient columns in unique constraint for partition key" in PostgreSQL
ERROR 42501: must be owner of table
How to fix "must be owner of table" in PostgreSQL
trigger cannot change partition destination
How to fix "Trigger cannot change partition destination" in PostgreSQL
SSL error: certificate does not match host name
SSL error: certificate does not match host name in PostgreSQL
No SSL connection
No SSL connection to PostgreSQL