3F000 invalid_schema_name

速览

SQLSTATE 3F000 是 Class 3F 中的 invalid_schema_name。3F000 表示已建立会话无法解析 schema 名称。选定的限定表路径得到 schema "<generated>" does not exist；固定的 namespace 和 schema 命令路径还覆盖对象创建等 SQL 阶段的解析，它不只是一个 search_path 提示。

含义

当 schema 名称本身无法解析时，namespace 查找会发出此条件。限定引用不存在的 schema 时使用 schema "%s" does not exist；未限定的 CREATE 没有可用创建命名空间时使用 no schema has been selected to create in。两者都是 schema 解析分支。普通未限定关系查找不到关系时使用 42P01，即使原因是 search_path 不合适；权限不足则进入 42501。

首先要判断失败的名称是 schema 还是关系。missing_schema.repaired_table 这样的限定引用会要求 namespace 代码解析准确的 schema，可以产生 3F000；没有显式 schema 的 CREATE 在没有可选创建 schema 时也可以产生 3F000。相反，SELECT * FROM missing_table 是未限定关系查找，通常产生 42P01；search_path 只决定搜索哪些关系，不会把该 SQLSTATE 变成 3F000。角色缺少所需权限时进入 42501。即使应用都报告“找不到 schema”，这些分支的修复也不同。

诊断

区分明确缺失的 schema、没有选定创建 schema 的 CREATE、未限定关系查找，以及 42501 权限不足。选定自动提交会话在 ERROR 后保持 IDLE；所有者显式创建目标 schema 和表，插入一行，并在明确命名空间下核对。检查失败命令使用的相同角色和数据库。

使用失败命令的相同角色和数据库检查标识符，例如查看 current_schemas(true)，并确认目标 schema 能否在目录中解析。再核对命令是否限定名称：选定案例有意引用不存在的限定 schema；如果是未限定 CREATE，要检查 search_path 是否有可用创建目标；如果是未限定关系读取，关系缺失应归为 42P01，而不是 3F000。显式事务中的选定 ERROR 可能使事务进入 INERROR；自动提交的 IDLE 不是通用恢复结果。

处理

使用迁移或所有者连接执行 CREATE SCHEMA，设置或限定目标命名空间，并用同一角色验证对象。对于 no schema has been selected to create in，应选择允许创建的 schema 或限定 CREATE；对于未限定的缺失关系，应修复关系名或目标 search_path，在关系可解析前应预期 42P01。不要通过添加无关 schema 到 search_path 掩盖命名空间错误；如果名称是有意删除的，应修复迁移或目标，而不是原样重试。

创建或暴露 schema 后，用同一角色重跑准确的限定语句，并核对最终对象。若失败语句位于显式事务中，应先回滚或回到预先设计的保存点，再执行无关 DDL。不要用扩大 schema 权限代替检查应用连接的数据库或使用的标识符。

实测诊断

固定的 namespace 路径在明确缺失 schema 时以 ERROR 发出主报文 schema "%s" does not exist，在未限定 CREATE 没有活动创建命名空间时发出 no schema has been selected to create in。选定的限定表案例没有固定 DETAIL 或 HINT。未限定关系查找不到时是独立的 42P01 relation "%s" does not exist 路径，角色权限不足则是 42501。

选定的动态名称为 c3f000_invalid_schema_name_missing，错误发生在会话建立后，没有固定 DETAIL 或 HINT。这与源码确认的 schema 命令路径，以及启动阶段的客户端失败不同。

代表案例

此 SQL 块限定不存在的 schema，创建 schema 与表，插入一行并核对，最后删除临时 schema。

CREATE TABLE missing_schema.repaired_table (id integer);
CREATE SCHEMA missing_schema;
CREATE TABLE missing_schema.repaired_table (id integer);
INSERT INTO missing_schema.repaired_table VALUES (1);
SELECT count(*) FROM missing_schema.repaired_table;
DROP SCHEMA missing_schema CASCADE;

18.6 运行记录 SQLSTATE 为 3F000，主报文 schema "c3f000_invalid_schema_name_missing" does not exist；断言的错误后状态为 IDLE，随后探针/修复成功。18.6 与 10.21 的断言和清理均通过。

可下载的案例与证据投影分别是 3F000 案例 JSON 和 作者证据。运行器清单为 verify/cases/3F000/cases.json；发布前会将页面 SQL 与共享注册表比对。

版本

上面的生成事实表记录锁定的目录快照和最早观察到的定义。本页自然运行范围是 PostgreSQL 18.6 与 10.21，不能据此推断所有中间版本的行为。

相关

• 3D000 — invalid_catalog_name
• 42501 — 相关条件

来源

• 上游源码 doc/src/sgml/xact.sgml PG18-docs 724edf9bd b48fbe8b
• 上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
• 上游源码 src/backend/catalog/namespace.c 第 2967–3004 行 REL_10_23 02991e79f 74833354
• 上游源码 src/backend/catalog/namespace.c 第 3022–3024 行 REL_10_23 02991e79f 74833354
• 上游源码 src/backend/catalog/namespace.c 第 3545–3547 行 REL_18_6 724edf9bd 8c9e6a99
• 上游源码 src/backend/parser/parse_relation.c 第 1147–1184 行 REL_10_23 02991e79f a34f40fc
• 核验材料 verify/cases/3F000/cases.json workspace 24f38a52
• 核验材料 verify/cases/3F000/snippets.json workspace a51e3e0d
• 核验材料 raw/calls/REL_10_23.jsonl REL_10_23 00d16d3e
• 核验材料 raw/calls/REL_18_6.jsonl REL_18_6 9ee8a0e8