PostgreSQL could not access file "$libdir/…"：服务端在自己的库目录里找不到这个 .so，先查是哪套安装、哪个库在引用

同一句报错，这几种写法都会触发（PG 17.12 / 16.16 测试库实测）

2026-11-13 我在 box 本机起了 PostgreSQL 17.12 和 16.16 两个测试实例（测试库、自造数据，PG 16.16/17.12（apt.postgresql.org 的 Debian 包解包到实验目录，lc_messages=C），非客户环境），用 \set VERBOSITY verbose 把 SQLSTATE 和源码位置一起打出来。下表每一行都是 psql 原样输出，单条耗时 25–37 ms（含建连接）：

结论：报错里引号中的字符串就是 pg_proc.probin 里存的原样路径（$libdir/ 前缀没展开），所以拿它去全库搜「是谁在引用」最快，见下文「升级前清单」一节。

老连接照常、新连接报错：.so 被删后为什么像「偶发故障」

我先在 17.12 测试库装 pg_trgm 1.5，建表 sku（2 万行自造数据）和 GIN 三元组索引 sku_title_trgm，然后把 pg_trgm.so 改名，模拟「包被卸载 / 新版本没装这个扩展」。结果按连接分成两派：

这解释了线上常见的错觉：连接池里活得久的连接早就把库载入了内存，照常工作；新建的连接才报错，于是看起来时好时坏。写入也会挂——表上只要有依赖这个扩展的索引，INSERT 就报，而简单的 count(*) 不受影响，容易被误判成「数据没问题、是应用的 bug」。

把文件放回原处后，新会话立即恢复（similarity() 27 ms 返回、索引查询 30 ms 返回 11 行），不需要重启；但老连接里载入的仍是旧文件，换了新版本 .so 时最好让连接池重建连接。

ALTER EXTENSION UPDATE 成功，不能证明库文件已就位

很多升级手册把「跑一遍 ALTER EXTENSION … UPDATE 没报错」当成扩展验收。我在 pg_trgm.so 已被改名的状态下执行 ALTER EXTENSION pg_trgm UPDATE，29 ms 返回 ALTER EXTENSION，版本从 1.5 变成了 1.6——而此时任何新会话一调用它就报 58P01。

原因在升级脚本：17 自带的 pg_trgm--1.5--1.6.sql 只有两条 ALTER OPERATOR FAMILY … ADD OPERATOR，不创建也不调用 C 函数，所以根本不加载 .so。别的扩展的升级脚本未必如此，但结论一样：UPDATE 只说明脚本跑完了。

我用的验收方式：新开一个连接，调用一次该扩展里的 C 函数，再跑一条会走它索引的查询；两条都返回才算库在。版本差用只读 SQL 查（测试库在 1.5 时输出 pg_trgm installed 1.5 / available 1.6）：

SELECT e.extname, e.extversion AS installed, a.default_version AS available
FROM pg_extension e
LEFT JOIN pg_available_extensions a ON a.name = e.extname
ORDER BY 1;

$libdir 到底是哪个目录：别信你 shell 里的 pg_config

官方文档说 $libdir 实际指向的目录可以用命令 pg_config --pkglibdir 查。但机器上装了不止一套 PostgreSQL 时（发行版包 + 官方源包、多个大版本、容器外再装一套客户端），命令行的 pg_config 不一定属于正在运行的服务端。测试机上正好是这种情况：

两个目录不是同一个——如果照命令行的结果去放 .so，服务端照样找不到。以服务端视图为准（默认只有超级用户可读）：

SELECT name, setting FROM pg_config
WHERE name IN ('VERSION', 'PKGLIBDIR', 'SHAREDIR');
SHOW dynamic_library_path;

ls <PKGLIBDIR> | grep -E 'pg_trgm|你的扩展名'
ldd <PKGLIBDIR>/pg_trgm.so | grep 'not found'   # 文件在但依赖的系统库缺

shared_preload_libraries 写错：不是报错，是服务起不来

预加载库在服务启动时就载入，找不到文件不会留给 SQL 去报，而是整个实例退出。我在 17.12 测试库执行 ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statement'（少了一个 s），ALTER SYSTEM 本身照样成功，重启时才出事：pg_ctl start 返回 rc=1，约 114 ms 退出，日志是：

FATAL:  could not access file "pg_stat_statement": No such file or directory
LOG:  database system is shut down

服务起不来就没法再用 ALTER SYSTEM 改回去。我的做法是直接编辑数据目录里的 postgresql.auto.conf，删掉那一行（或改成正确拼写），再 pg_ctl start，110 ms 起来。如果值写在 postgresql.conf，就改那个文件。改之前先备份这个文件。

反过来，扩展需要预加载却没配，报的是另一句：pg_stat_statements must be loaded via "shared_preload_libraries"（55000），而且 CREATE EXTENSION pg_stat_statements 本身会成功，查视图时才报——见 extension is not available 页。

把 16 版的 .so 拷进 17：报错换了，问题没解决

升级后缺库，最顺手的「修法」是把旧版本目录里的 .so 拷过来。我把 PG 16.16 的几个 contrib 库直接拿给 17.12 去 LOAD：

也就是说，58P01 说明文件不在；XX000 说明文件在但不是给这个版本编译的。看到后者别再换着拷了，去装目标大版本的扩展包。

pg_upgrade 16→17：--check 报 loadable libraries missing 怎么读、怎么修

我在 16.16 旧集群建了自造库 shop，装 pg_trgm、adminpack、old_snapshot，再建一个 C 函数 inch_lev 指向 $libdir/inch16only（模拟「只给旧版本装过」的第三方库），然后对 17.12 新集群跑 pg_upgrade --check。620 ms 后失败，原文：

Checking for presence of required libraries                   fatal

Your installation references loadable libraries that are missing from the
new installation.  You can add these libraries to the new installation,
or remove the functions using them from the old installation.  A list of
problem libraries is in the file:
    …/new17data/pg_upgrade_output.d/20261113T114446.087/loadable_libraries.txt

could not load library "$libdir/adminpack": ERROR:  could not access file "$libdir/adminpack": No such file or directory
In database: shop
could not load library "$libdir/inch16only": ERROR:  could not access file "$libdir/inch16only": No such file or directory
In database: shop
could not load library "$libdir/old_snapshot": ERROR:  could not access file "$libdir/old_snapshot": No such file or directory
In database: shop

1. adminpack、old_snapshot 是 PG17 已移除的 contrib（17 的发布说明写明移除 adminpack；old_snapshot 依赖的 old_snapshot_threshold 也在 17 移除，17 源码 contrib 目录里已没有它）。17 没有对应包可装，只能在旧集群 DROP EXTENSION adminpack; DROP EXTENSION old_snapshot;（33 ms）。
2. 自造的 inch16only：我先试了把 16 版的 .so 拷进 17 的库目录，再跑 --check，仍然 fatal（640 ms），文件里的原因变成 undefined symbol: pg_utf_mblen——--check 会真的去加载，拷文件骗不过它。
3. 换成 17 版构建的库后 --check 通过（630 ms，*Clusters are compatible*），pg_upgrade --copy 实升 1870 ms（测试库很小，时长不代表你的库），新集群里 inch_lev() 返回 1、pg_trgm 1.6 的 similarity() 返回 0.78571427。

未测：真实 PostGIS / TimescaleDB 等第三方包的 17 版安装、pg_upgrade --link 模式、Windows 与 RPM 的目录布局、Docker 官方镜像；也没有触发 pg_upgrade 生成 update_extensions.sql 的场景（本次 16/17 的 pg_trgm 都是 1.6）。这些情况请以对应扩展和发行版的文档为准。

升级前清单：每个库跑一遍 pg_proc.probin，对着新版本库目录核对

pg_proc 是每个数据库各自一份，loadable_libraries.txt 也是按库列的（In database: shop）。所以清单要在每个库里跑，而不只是在 postgres 库里跑一次：

SELECT probin, count(*) AS funcs
FROM pg_proc
WHERE probin IS NOT NULL
GROUP BY probin
ORDER BY 1;

测试库 16.16 的 shop 库，去掉内置的编码转换库（*_and_*）、plpgsql、dict_snowball 后剩 5 行：$libdir/adminpack 5 个函数、$libdir/euc2004_sjis2004 2、$libdir/inch16only 1、$libdir/old_snapshot 1、$libdir/pg_trgm 31。拿这张表去新版本的 PKGLIBDIR 里逐个 ls，缺哪个、是不是 17 已移除的，升级前就一清二楚。

我的判断：这张表比 pg_upgrade --check 更早、更全——--check 要等新集群 initdb 好才能跑，而且遇到第一个 fatal 类别就退出；清单在旧库上随时能跑，也能顺带发现不属于任何扩展、直接写死路径的自定义 C 函数（probin NOT LIKE '$libdir/%'）。

修复顺序（生产库）

1. 看报错里的路径：$libdir/xxx 或裸名 → 去服务端 pg_config 视图的 PKGLIBDIR 找 xxx.so；绝对路径 → 直接检查那个路径。
2. 确认是哪套安装：服务端视图的 VERSION 和 PKGLIBDIR，别用命令行 pg_config 代替。
3. 缺文件 → 用操作系统包管理器装与服务端大版本一致的扩展包；装好后新连接即可用，不必重启（预加载的库除外）。
4. 扩展已不再需要 → DROP EXTENSION。测试库里 .so 缺失时 DROP 也能执行（31 ms）；有依赖索引时报 2BP01 cannot drop extension pg_trgm because other objects depend on it，先 DROP INDEX 或评估后 CASCADE。
5. 服务起不来（预加载写错）→ 改 postgresql.auto.conf / postgresql.conf 里的 shared_preload_libraries 后再启动。
6. 验收：新开连接调用一次扩展的 C 函数、跑一条走它索引的查询；不要只看 ALTER EXTENSION UPDATE 是否成功。重装扩展后要重建依赖它的索引（测试库重装 pg_trgm + 重建 2 万行 GIN 索引 87 ms）。

常见问题

相关错误码

• extension-is-not-available · extension is not available（0A000，扩展 control 文件不在）
• could-not-connect-to-server · could not connect to server（服务没起来时客户端看到的）
• permission-denied-for-table · permission denied for table（42501）
• canceling-statement-due-to-statement-timeout · canceling statement due to statement timeout

• PostgreSQL 报错速查（汇总页）
• 支柱页：数据库故障先查什么（MySQL + PostgreSQL 诊断树）
• PostgreSQL 升级后变慢：统计信息之外的 4 个原因（含扩展版本）

← 返回PostgreSQL 连接报错速查

下一步

价格以对应页面当前标价为准。