# HV000 — fdw_error（外部数据包装器错误）

> PostgreSQL SQLSTATE HV000 是 SQL/MED 外部数据包装器的通用错误条件。应先确认包装器回调和远端诊断，再决定恢复方式。
---

# HV000 — fdw_error（外部数据包装器错误）

## 速览 {#at-a-glance}

`HV000` 是 SQL/MED 外部数据包装器（FDW）的通用错误条件，只说明错误位于 FDW 边界，不对应某一种远端故障、回调或重试策略。PostgreSQL 18.6 核心/contrib 扫描没有解析出直接的 `ERRCODE_FDW_ERROR` 报告组，具体触发方式取决于安装的实现。

包装器回调可以报告自己的 SQLSTATE，访问另一系统的包装器也可能转发远端诊断。解释 `HV000` 前，应保留完整诊断、外部表、外部服务器、包装器名称与版本以及操作阶段。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `HV000` |
| 条件名 | `fdw_error` |
| 状态 | `有效` |
| 已知存在于 | `9.1.0` |
| 锁定快照 | `9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_FDW_ERROR` |
| 别名 | `—` |

<!-- source facts: data/errcodes/HV000.json -->
<!-- END SQLSTATE FACTS -->

## 含义与范围 {#meaning}

18.6 定义为 SQL/MED 专用 Class HV 中的 `HV000 E ERRCODE_FDW_ERROR fdw_error`。FDW API 提供规划、扫描、修改、导入和解释回调；执行器通过安装的包装器提供的 FDW routine 调用这些回调。条件集中定义而具体实现位于扩展，正是这个边界的结果。

`postgres_fdw`、`file_fdw` 和第三方 FDW 实现 FDW 回调 API。dblink 是独立的 contrib 客户端 API，访问另一 PostgreSQL 服务器时也可能使用 Class HV 代码，但它不是 FDW 回调实现。远端 SQLSTATE、libpq 连接错误和包装器本地错误可能出现在一次操作中，但不能互相替代。

## 报文与诊断 {#messages}

归档的 18.6 调用扫描没有解析出 `HV000` 的稳定核心报文变体。尽可能保留 `C`/SQLSTATE、`S`、`V`、`M`、`D`、`H`、`W`、`F`、`L`、`R`，以及包装器回调或远端命令；不能用“FDW error”概括实际报文。

## 诊断 {#diagnosis}

先确定阶段：规划、扫描初始化、取数、增删改、提交/回滚、模式导入或 `EXPLAIN`。再检查外部表和服务器选项、用户映射、包装器版本及远端日志。若是远端 PostgreSQL 包装器，要分别记录远端和本地 SQLSTATE；它们描述的是同一故障的不同层。

本次扫描覆盖 PostgreSQL 18.6 核心及自带 contrib 源码，不覆盖所有外部包装器、驱动、远端数据库或用户回调。

## 处理 {#response}

根据已确认的层次修复外部服务器或用户映射、包装器选项/回调契约、远端操作，或安装兼容的包装器版本。只有确认包装器是否已访问远端以及写操作是否可能提交后才重试；单独的 `HV000` 不能证明这两点。

## 版本 {#versions}

锁定目录在 9.1.0 已观察到 `HV000`，并存在于截至 18.6 的正式快照及 19 Beta 3 预览快照。pre-9 扫描的 7.4–8.4 定义文件未观察到它，这只是资料边界，不是精确引入版本。

## 相关 {#related}

比较 [`HV001` — `fdw_out_of_memory`](../hv001/)、[`HV002` — `fdw_dynamic_parameter_value_needed`](../hv002/) 和 [`HV00B` — `fdw_invalid_handle`](../hv00b/)。远端条件应按远端系统的 SQLSTATE 和诊断解释。

## 来源 {#sources}

- [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L456-L477) — 18.6 固定定义，SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba`。
- [`fdwapi.h`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/foreign/fdwapi.h#L24-L55) — 回调边界。
- [`nodeForeignscan.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/executor/nodeForeignscan.c#L40-L70) — 执行器回调分发。
- [结构化证据](../../data/evidence/hv000.json) — 固定来源和有界调用扫描结果。