inchTodd/db-error-troubleshooting-skills / skills/pg-role-does-not-exist
pg-role-does-not-exist
Verified排查 PostgreSQL 报错「role "%s" does not exist」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
SKILL.md
View on GitHub---
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |