# HV002 — fdw_dynamic_parameter_value_needed

> PostgreSQL SQLSTATE HV002 reports a required FDW parameter that is unavailable. file_fdw raises it when a foreign table has neither filename nor program.
---

# HV002 — fdw_dynamic_parameter_value_needed

## At a glance {#at-a-glance}

`HV002` says that an FDW operation needs a parameter value that was not available. PostgreSQL 18.6's bundled `file_fdw` validator raises it during foreign-table option validation when neither `filename` nor `program` is supplied.

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

| Field | Value |
| --- | --- |
| SQLSTATE | `HV002` |
| Condition | `fdw_dynamic_parameter_value_needed` |
| Status | `active` |
| Known present by | `9.1.0` |
| Locked snapshots | `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` |
| Macros | `ERRCODE_FDW_DYNAMIC_PARAMETER_VALUE_NEEDED` |
| Aliases | `—` |

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

## Meaning and trigger paths {#meaning}

In `contrib/file_fdw/file_fdw.c`, the validator checks `ForeignTableRelationId` options and raises `ERROR` with `either filename or program is required for file_fdw foreign tables` when both values are absent. The condition name is broader than this one implementation: another FDW may need a value at planning, scan, or modify time and report a different message.

## Messages and diagnostics {#messages}

The fixed 18.6 variant is `ERROR: either filename or program is required for file_fdw foreign tables` from `file_fdw_validator`, lines 345-350. The fixed 9.1.24 source uses `ERROR: filename is required for file_fdw foreign tables`; neither source template adds a detail or hint. These are local option-validation errors; they do not mean a remote program failed to start.

## Diagnosis {#diagnosis}

Inspect the exact `CREATE FOREIGN TABLE` or `ALTER FOREIGN TABLE ... OPTIONS` definition and the wrapper's accepted option names. For `file_fdw`, check that exactly one usable source option is present and that its value is visible to the server process. For another wrapper, locate its validator or callback and read its own required-parameter contract.

## Response {#response}

Add the required FDW option with the correct spelling and permissions, or use the wrapper's supported dynamic parameter mechanism. Re-run validation or the original operation after checking the foreign server and table identity. Retrying unchanged SQL cannot provide a missing value and is not a recovery strategy.

## Versions {#versions}

`HV002` is observed from 9.1.0 through 18.6 and the 19 Beta 3 preview. The fixed 9.1.24 `file_fdw` source uses “filename is required”, while the fixed 18.6 source uses “either filename or program is required”; use the server version when matching the message. This does not claim the exact release where the wording changed.

## Related {#related}

[`HV00D`](../hv00d/) concerns an option name the wrapper does not recognize. [`HV000`](../hv000/) is a generic wrapper failure. [`HV005`](../hv005/) concerns a missing foreign column rather than a missing FDW option.

## Sources {#sources}

- [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L461) — definition, SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba`.
- [`file_fdw.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/file_fdw/file_fdw.c#L345-L350) — validator condition and message.
- [Historical `file_fdw.c` 9.1.24](https://github.com/postgres/postgres/blob/e85493559c4678f54d30b6b4e04b17c03a3192d7/contrib/file_fdw/file_fdw.c#L218-L224) — fixed filename-only validator message, SHA-256 `6f948ed8f9ffa6d1077b289f23c53eff02c5182492f0827b908c2be86026dad8`.
- [Structured evidence](../data/evidence/hv002.json) — source path and historical message boundary.