Skip to content

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

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.

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 —

Meaning and trigger paths

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

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

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

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

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.

HV00D concerns an option name the wrapper does not recognize. HV000 is a generic wrapper failure. HV005 concerns a missing foreign column rather than a missing FDW option.

Sources

  • errcodes.txt — definition, SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba.
  • file_fdw.c — validator condition and message.
  • Historical file_fdw.c 9.1.24 — fixed filename-only validator message, SHA-256 6f948ed8f9ffa6d1077b289f23c53eff02c5182492f0827b908c2be86026dad8.
  • Structured evidence — source path and historical message boundary.