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」。当用户贴出包含这条报错的输出、或问这条报错怎么解决时使用。只读排查优先,不需要也不收集数据库密码。

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。

关键事实

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

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

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

来源例子常见坑
命令行 -U 或连接串里的 userpsql -U app、postgresql://app@host/db连接串写错、环境变量覆盖
环境变量 PGUSERexport PGUSER=appCI、容器里残留的旧变量
都没写时:操作系统用户名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。

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

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

# 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 都要加引号。

补建用户:最小权限写法

-- 以超级用户连接(如 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 不承诺任何修复效果。

来源

完整图文版和相关报错: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: 118kUpdated 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: 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
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