# HV002 — fdw_dynamic_parameter_value_needed（需要外部数据包装器动态参数）

> PostgreSQL SQLSTATE HV002 表示 FDW 所需参数不可用。file_fdw 在外部表既没有 filename 也没有 program 时报告它。
---

# HV002 — fdw_dynamic_parameter_value_needed

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

`HV002` 表示 FDW 操作所需的参数值不可用。PostgreSQL 18.6 自带的 `file_fdw` 在外部表选项校验期间发现 `filename` 和 `program` 都没有提供时报告此码。

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

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

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

## 含义与触发路径 {#meaning}

`contrib/file_fdw/file_fdw.c` 的校验器检查 `ForeignTableRelationId` 的选项；两者都缺失时以 `ERROR` 报告 `either filename or program is required for file_fdw foreign tables`。条件名比这一实现更宽，其他包装器可能在规划、扫描或修改阶段需要不同参数并产生不同报文。

## 报文与诊断 {#messages}

18.6 固定变体来自 `file_fdw_validator` 第 345–350 行：`ERROR: either filename or program is required for file_fdw foreign tables`。固定的 9.1.24 源码使用 `ERROR: filename is required for file_fdw foreign tables`；两个源码模板都没有 detail 或 hint。这些都是本地选项校验错误，不表示远端程序启动失败。

## 诊断 {#diagnosis}

检查具体的 `CREATE FOREIGN TABLE` 或 `ALTER FOREIGN TABLE ... OPTIONS` 定义及包装器接受的选项名。对 `file_fdw`，确认有一个可用的源选项且服务器进程能访问其值；其他包装器应查其校验器或回调的参数契约。

## 处理 {#response}

按包装器要求补上正确拼写和权限的选项，或使用其支持的动态参数机制；随后重新校验。未改变 SQL 就重试不能生成缺失参数。

## 版本 {#versions}

目录从 9.1.0 观察到 `HV002`，延续到 18.6 和 19 Beta 3。固定的 9.1.24 `file_fdw` 源码使用 “filename is required”，固定的 18.6 源码使用 “either filename or program is required”，匹配报文时要看服务器版本；这里不声称具体的变更发布版本。

## 相关 {#related}

[`HV00D`](../hv00d/) 是包装器不认识选项名；[`HV000`](../hv000/) 是通用包装器失败；[`HV005`](../hv005/) 是外部列缺失而非 FDW 选项缺失。

## 来源 {#sources}

- [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L461) — 定义，SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba`。
- [`file_fdw.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/file_fdw/file_fdw.c#L345-L350) — 校验条件与报文。
- [9.1.24 历史 `file_fdw.c`](https://github.com/postgres/postgres/blob/e85493559c4678f54d30b6b4e04b17c03a3192d7/contrib/file_fdw/file_fdw.c#L218-L224) — 固定的 filename-only 校验报文，SHA-256 `6f948ed8f9ffa6d1077b289f23c53eff02c5182492f0827b908c2be86026dad8`。
- [结构化证据](../../data/evidence/hv002.json) — 源码路径与历史报文边界。