# HV009 — fdw_invalid_use_of_null_pointer（外部数据包装器非法使用空指针）

> PostgreSQL SQLSTATE HV009 表示 FDW 违反空指针契约。应定位实际包装器回调并保留失败上下文。
---

# HV009 — fdw_invalid_use_of_null_pointer

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

`HV009` 描述 FDW 边界的非法空指针使用。18.6 核心/contrib 调用扫描没有直接报告组，因此没有安全的 SQL 复现或自带报文。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `HV009` |
| 条件名 | `fdw_invalid_use_of_null_pointer` |
| 状态 | `有效` |
| 已知存在于 | `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_INVALID_USE_OF_NULL_POINTER` |
| 别名 | `—` |

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

## 含义 {#meaning}

它用于包装器/API 契约中的空指针问题，例如包装器把缺少的描述符、handle 或回调结果当成存在。它不是普通 SQL `NULL` 值错误，不能从可空列推断。

## 报文与诊断 {#messages}

没有固定核心报文。保留拥有该指针的回调、handle/描述符、包装器构建版本和服务器日志；实现不同也可能表现为崩溃、`XX000` 或驱动异常。

## 诊断 {#diagnosis}

在源码证明前，把它按包装器缺陷或契约/ABI 不匹配处理。检查回调实现和版本，确认远端断开或分配失败是否制造了空状态；不要从 SQL 侧解引用或修复对象。

## 处理 {#response}

包装器缺陷存在时不要继续重试。保留日志，在一次性环境隔离外部表/服务器，确认后升级或修补包装器；若进程或连接已终止，按相应组件的恢复流程处理。

## 版本 {#versions}

目录从 9.1.0 观察到该码，延续到 18.6 与 19 Beta 3；pre-9 定义扫描未观察到，精确实现引入未知。

## 相关 {#related}

[`HV00B`](../hv00b/) 是无效 FDW handle；[`XX000`](../xx000/) 是更宽的内部错误边界。普通 SQL 空值条件属于 Class 22。

## 来源 {#sources}

- [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L475) — 定义，SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba`。
- [`fdwapi.h`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/foreign/fdwapi.h#L24-L55) — 回调边界。
- [结构化证据](../../data/evidence/hv009.json) — 有界扫描与来源边界。