Skip to content

inchTodd/db-error-troubleshooting-skills / skills/pg-role-does-not-exist

pg-role-does-not-exist

Verified

排查 PostgreSQL 报错「role "%s" does not exist」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。

FileKindSize
SKILL.mdskill md8.4 KB
---
name: pg-role-does-not-exist
description: "排查 PostgreSQL 报错「role \"%s\" does not exist」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。"
---

# PostgreSQL「role does not exist」:服务器上没有这个用户名,先确认连的是哪台库、用的是哪个名字

> 原文与完整版:https://surinch.com/tools/postgresql-error/role-does-not-exist(最后核对 2026-11-05)

## 一句话结论

这条报错说明你要登录的数据库用户名在这台服务器上不存在。最常见的三种情况:`psql` 没写 `-U`,默认拿操作系统用户名(如 `ubuntu`)去登录;Docker 容器复用了旧数据卷,`POSTGRES_USER` 没生效;建用户时没加双引号,`MyUser` 实际被建成了 `myuser`。先用 `sudo -u postgres psql -c '\du'` 看现有用户,再用 `CREATE ROLE ... LOGIN` 补建,或把连接串里的用户名改对。

## 官方报错原文

```
role "%s" does not exist
```

出自 PostgreSQL 源码 miscinit.c 的 InitializeSessionUserId(),以 FATAL 级别报出,错误码 `ERRCODE_INVALID_AUTHORIZATION_SPECIFICATION`(SQLSTATE 28000)。客户端看到的完整形式一般是 `psql: error: connection to server on socket "..." failed: FATAL:  role "ubuntu" does not exist`。

## 关键事实

| 项 | 内容 |
|---|---|
| SQLSTATE | `28000`(invalid_authorization_specification) |
| 报错时机 | 通过 pg_hba.conf 认证之后、建立会话时查 pg_authid 找不到该名字 |
| 密码认证时 | 客户端只看到 `password authentication failed`;服务器日志 DETAIL 写 `Role "xxx" does not exist.` |
| psql 默认用户名 | 操作系统用户名;默认数据库名 = 用户名 |
| Docker 镜像 | `POSTGRES_USER` 只在数据目录为空、首次初始化时创建 |

## 先弄清楚:服务器收到的到底是哪个用户名

报错里引号中的名字就是服务器收到的用户名,它往往不是你以为的那个。客户端没有显式指定用户名时,会按下面的顺序取值:

| 来源 | 例子 | 常见坑 |
|---|---|---|
| 命令行 `-U` 或连接串里的 user | `psql -U app`、`postgresql://app@host/db` | 连接串写错、环境变量覆盖 |
| 环境变量 `PGUSER` | `export PGUSER=app` | CI、容器里残留的旧变量 |
| 都没写时:操作系统用户名 | Linux 用户 `ubuntu` 执行 `psql` → 以 `ubuntu` 登录 | 新装的库里只有 `postgres` 一个用户 |

所以新装完 PostgreSQL 直接敲 `psql`,几乎必然得到 `role "你的系统用户名" does not exist`。这不是安装失败,而是库里只有 `postgres` 这个超级用户。

> 如果 pg_hba.conf 用的是密码认证(scram-sha-256 / md5),用户名不存在时服务器**故意**只回 `password authentication failed`,避免向客户端泄露“这个用户不存在”。这时要看服务器日志里的 `DETAIL:  Role "xxx" does not exist.`,见 [password authentication failed](https://surinch.com/tools/postgresql-error/password-authentication-failed)。


## Docker:改了 POSTGRES_USER 还是报错,多半是数据卷没清

官方 postgres 镜像文档写明:`POSTGRES_USER`、`POSTGRES_PASSWORD`、`POSTGRES_DB` 这些变量**只在数据目录为空时生效**,已有数据的卷启动时原样保留。典型过程是:第一次用默认配置起过容器(只建了 `postgres`),后来在 compose 里加上 `POSTGRES_USER=app`,重建容器但沿用了同一个卷,`app` 从来没被创建。

```bash
# 1) 看容器里实际有哪些用户(镜像内 Unix 套接字是 trust,可以直接进)
docker exec -it <容器名> psql -U postgres -c '\du'

# 2) 看数据卷是不是旧的
docker volume ls
docker inspect <容器名> --format '{{ json .Mounts }}'
```

- 数据不重要(本地开发):`docker compose down -v` 删除卷后重新 `up`,变量会在首次初始化时生效。**这会删掉卷里的全部数据**。
- 数据要保留:不要删卷,进容器用 `CREATE ROLE app LOGIN PASSWORD '...'` 手动补建,并按需 `GRANT`。
- 另一种常见情况:宿主机自己也装了 PostgreSQL 并占着 5432,你的客户端连的是宿主机上的库,不是容器。用 `ss -ltnp | grep 5432` 或换个映射端口(如 `5433:5432`)确认。


## 大小写:建的是 myuser,登录用的是 MyUser

SQL 里没加双引号的标识符会被折成小写,而客户端发来的用户名是原样比对的。两边对不上就会报 role does not exist:

| 建用户的语句 | 库里实际的名字 | `psql -U MyUser` 结果 |
|---|---|---|
| `CREATE ROLE MyUser LOGIN;` | `myuser` | 失败:role "MyUser" does not exist |
| `CREATE ROLE "MyUser" LOGIN;` | `MyUser` | 成功 |
| `CREATE ROLE myuser LOGIN;` | `myuser` | 用 `-U myuser` 成功 |

建议用户名一律用小写字母、数字和下划线,避免以后每条 SQL 都要加引号。


## 补建用户:最小权限写法

```sql
-- 以超级用户连接(如 sudo -u postgres psql)后执行
SELECT rolname, rolcanlogin, rolsuper FROM pg_roles ORDER BY rolname;  -- 只读:先看现有用户

CREATE ROLE app LOGIN PASSWORD '换成强密码';
CREATE DATABASE appdb OWNER app;   -- 需要独立库时
-- 或者只给已有库的权限:
GRANT CONNECT ON DATABASE appdb TO app;
```

- 想用和系统用户同名的账号免密登录本机:`sudo -u postgres createuser --interactive ubuntu`,再 `createdb -O ubuntu ubuntu`,之后直接 `psql` 即可(走 peer 认证)。
- 用户存在但报 `role "xxx" is not permitted to log in`:说明建成了 NOLOGIN(`CREATE ROLE` 默认就是 NOLOGIN),执行 `ALTER ROLE xxx LOGIN;`。
- 用户刚建好仍报错:确认连的是同一个实例(端口、容器、主机),`SELECT inet_server_addr(), inet_server_port();` 可以核对。

## 常见问题

**psql: FATAL: role "ubuntu" does not exist 怎么解决?**

psql 没指定 -U 时用操作系统用户名登录,新装的库里只有 postgres 用户。用 sudo -u postgres psql 进去,或者 sudo -u postgres createuser --interactive ubuntu 建一个同名用户。

**Docker 里设置了 POSTGRES_USER 为什么还是 role does not exist?**

POSTGRES_USER 只在数据目录为空、首次初始化时生效。沿用旧数据卷时不会创建新用户。开发环境可以删卷重建(会丢数据),要保留数据就进容器手动 CREATE ROLE。

**明明建了用户,为什么还提示不存在?**

多半是大小写:CREATE ROLE MyUser 实际建的是 myuser。要么登录时用小写,要么建用户时给名字加双引号。也要确认连的是同一个实例。

**为什么有时报 password authentication failed 而不是 role does not exist?**

pg_hba.conf 用密码认证时,用户不存在也只返回密码认证失败,避免泄露用户是否存在。服务器日志里会有 DETAIL: Role "xxx" does not exist.。

**role 和 user 有什么区别?**

在 PostgreSQL 里是同一种对象。CREATE USER 等于 CREATE ROLE 加 LOGIN 属性;没有 LOGIN 的 role 只能用来分组授权,不能登录。

## 给 agent 的使用守则

- 先让用户贴出完整报错和执行的命令,按上面的顺序做只读检查,再给修改建议。
- 不要求用户提供密码、连接串里的凭证或生产数据;需要时让用户自己在本机执行命令并贴结果(可先打码)。
- 改配置(pg_hba.conf、my.cnf、授权语句)前先说明影响并让用户确认;本 skill 不承诺任何修复效果。

## 来源

- [PostgreSQL 源码 REL_18_STABLE:src/backend/utils/init/miscinit.c(InitializeSessionUserId)](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/utils/init/miscinit.c)
- [PostgreSQL 源码 REL_18_STABLE:src/backend/libpq/crypt.c(get_role_password)](https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/libpq/crypt.c)
- [PostgreSQL 18 文档:psql(默认用户名与默认数据库名)](https://www.postgresql.org/docs/current/app-psql.html)
- [Docker 官方 postgres 镜像文档(POSTGRES_USER / POSTGRES_DB,仅空数据目录初始化时生效)](https://github.com/docker-library/docs/blob/master/postgres/content.md)
- [PostgreSQL 18 文档 4.1.1:Identifiers and Key Words(未加引号的标识符折叠为小写)](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)
- [PostgreSQL 18 文档:CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html)

完整图文版和相关报错:https://surinch.com/tools/postgresql-error/role-does-not-exist
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall