PostgreSQL 常见报错速查：12 条原文、含义与处置

2026-11-10 #数据库

报错文本本身就是最好的索引。下面这张表按"看到什么"来查，比按错误码查快。标注"实测"的是本机 18.6 抓到的原文，其余依据文档与常见语义。

1. 连接阶段

报错原文	含义	第一步
`FATAL: role "x" does not exist`	角色不存在（实测）	检查 `-U` 与 `pg_roles`；注意默认用当前系统用户名
`FATAL: database "x" does not exist`	库不存在（实测）	`psql -l` 看列表；`createdb` 或改 `PGDATABASE`
`FATAL: password authentication failed for user "x"`	密码错或认证方式不符	看 `pg_hba.conf` 的 method、`password_encryption`
`FATAL: no pg_hba.conf entry for host ...`	来源地址没被授权	加一条 host 规则，或改 `listen_addresses` 后 reload
`FATAL: sorry, too many clients already`	连接数打满	看 `max_connections` 与 `pg_stat_activity` 的连接来源，先查泄漏
`could not connect to server: Connection refused`	进程没起或没监听该地址	`pg_isready`、`ss -lntp`、`listen_addresses`

2. 执行阶段

报错原文	含义	第一步
`ERROR: relation "x" does not exist`	表/视图不在当前 search_path（实测）	`SHOW search_path`，必要时写全 `schema.table`
`ERROR: canceling statement due to statement timeout`	触发了 `statement_timeout`（实测）	看该会话的 timeout 设置，再决定优化 SQL 还是放宽
`ERROR: duplicate key value violates unique constraint`	唯一约束冲突	看是并发插入还是序列落后（逻辑复制迁移常见）
`ERROR: deadlock detected`	两个事务互相等待，被系统选一个牺牲	统一加锁顺序；缩短事务；必要时重试
`ERROR: could not extend file ... No space left on device`	数据目录满	`df -h`，再看 WAL 是否堆积、`pg_wal` 是否被订阅槽拖住
`old cluster does not use data checksums but the new one does`	升级时校验和设置不一致	旧库 `pg_checksums --enable` 或新库 `--no-data-checksums`

3. 先看这三样，再查具体报错

-- 当前会话/全局的关键设置
SHOW statement_timeout;
SHOW search_path;
SHOW max_connections;

-- 谁在占连接
SELECT usename, application_name, state, count(*)
FROM pg_stat_activity GROUP BY 1,2,3 ORDER BY 4 DESC;

4. 两个容易误判的

too many clients 不一定是业务量涨了。先看 state = 'idle' 的连接占比，连接池配置不当造成的空闲连接占满，比真实并发更常见。

relation does not exist 不一定是表被删了。九成是 search_path 或大小写问题：建表时用了双引号（"Orders"），查询时写 orders 就找不到。

小结

报错原文里的关键词比错误码有用：does not exist 指向对象解析，authentication/pg_hba 指向连接准入，timeout/deadlock 指向执行期竞争，No space 指向存储。

养成一个习惯：把完整报错连同 SQLSTATE 一起记录。psql 里加 \set VERBOSITY verbose 能看到错误码，搜文档和社区时比搜一句话描述精确得多。

数据来源与检索时间

检索时间 2026-11-10。标注"实测"的四条为本机 18.6 抓取，其余依据文档语义整理。

来源	URL	对应数据
PostgreSQL 18 文档《21.3 Authentication`（客户端认证）	https://www.postgresql.org/docs/18/client-authentication.html	`pg_hba.conf` 规则匹配与 `password authentication failed`、`no pg_hba.conf entry` 的产生条件
PostgreSQL 18 文档《20.1 连接与认证问题》	https://www.postgresql.org/docs/18/runtime-config-connection.html	`listen_addresses`、`max_connections` 与 `too many clients`
PostgreSQL 18 文档《pg_upgrade》	https://www.postgresql.org/docs/18/pgupgrade.html	data checksums 不一致导致的拒绝升级

核验说明

role、database、relation、statement timeout 四条为实跑输出；too many clients、deadlock detected、No space left、pg_hba 两类未在本机复现，依据文档与错误语义说明。
未覆盖：复制相关报错（replication slot、logical replication）、扩展与编码错误。它们各自有成组的原因，塞进这张表会失真。

#数据库