# HV000 — fdw_error

> PostgreSQL SQLSTATE HV000 is the SQL/MED foreign-data-wrapper error condition. Identify the wrapper callback and any remote diagnostic before deciding how to recover.
---

# HV000 — fdw_error

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

`HV000` is the generic SQL/MED foreign-data-wrapper error condition. It identifies the FDW error class, not a particular remote failure, callback, or retry policy. No direct `ERRCODE_FDW_ERROR` report group was resolved in the PostgreSQL 18.6 core/contrib scan; the concrete trigger therefore depends on the installed implementation.

An FDW callback may report its own SQLSTATE, and a wrapper that talks to another system may forward a remote diagnostic. Record the complete diagnostic and the foreign table, server, wrapper name/version, and operation before interpreting `HV000`.

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

| Field | Value |
| --- | --- |
| SQLSTATE | `HV000` |
| Condition | `fdw_error` |
| 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_ERROR` |
| Aliases | `—` |

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

## Meaning and scope {#meaning}

The 18.6 definition is `HV000 E ERRCODE_FDW_ERROR fdw_error` in the SQL/MED-specific Class HV. The FDW API exposes planning, scan, modification, import, and explanation callbacks; the executor invokes those callbacks through an FDW routine supplied by the installed wrapper. That API boundary explains why the condition is defined centrally while concrete implementations live in extensions.

`postgres_fdw`, `file_fdw`, and third-party FDWs implement the FDW callback API. dblink is a separate contrib client API that can itself use Class HV codes while talking to another PostgreSQL server; it is not an FDW callback implementation. A remote server's SQLSTATE, a libpq connection error, and a wrapper's locally raised error can all appear in one user operation, but they are not interchangeable evidence for `HV000`.

## Messages and diagnostics {#messages}

No stable 18.6 core message variant for `HV000` was resolved in the archived call scan. Preserve `C`/SQLSTATE, `S`, `V`, `M`, `D`, `H`, `W`, `F`, `L`, and `R` where supplied, together with the wrapper callback or remote command. Do not substitute a generic “FDW error” string for the actual message.

## Diagnosis {#diagnosis}

First identify the phase: planning, scan initialization, fetch, insert/update/delete, commit/rollback, schema import, or `EXPLAIN`. Then inspect the foreign table and server options, user mapping, wrapper extension version, and any remote connection log. For a remote PostgreSQL wrapper, compare the remote SQLSTATE and fields with the local wrapper error; they can describe different layers of the same failure.

The source scan covered PostgreSQL 18.6 core and bundled `contrib` sources; it does not cover every external wrapper, driver, remote database, or user-defined callback.

## Response {#response}

Use the identified layer to choose the repair: correct the foreign server or user mapping, fix the wrapper option or callback contract, repair the remote operation, or install a compatible wrapper version. Retry only after checking whether the wrapper reached the remote system and whether a write may have been committed; `HV000` alone does not establish either fact.

Do not catch every Class HV value and blindly retry. Preserve the original fields and consult the wrapper's documented transaction and reconnect behavior.

## Versions {#versions}

The locked catalogue first observes `HV000` in PostgreSQL 9.1.0 and includes it in every formal snapshot through 18.6 and the 19 Beta 3 preview. The pre-9 scan did not observe it in the available 7.4–8.4 definition files; that is a source boundary, not an exact introduction claim.

## Related {#related}

Compare [`HV001` — `fdw_out_of_memory`](../hv001/), [`HV002` — `fdw_dynamic_parameter_value_needed`](../hv002/), and [`HV00B` — `fdw_invalid_handle`](../hv00b/). Remote server conditions must be interpreted using the remote system's own SQLSTATE and diagnostics.

## Sources {#sources}

- [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L456-L477) — fixed PostgreSQL 18.6 definition (`src.errcodes.18.6`, SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba`).
- [`fdwapi.h`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/include/foreign/fdwapi.h#L24-L55) — callback boundary (`src.fdwapi.18.6`).
- [`nodeForeignscan.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/executor/nodeForeignscan.c#L40-L70) — executor callback dispatch (`src.nodeforeignscan.18.6`).
- [`FDW callback documentation`](https://www.postgresql.org/docs/18/fdwhandler.html) — callback responsibilities and error boundary (`doc.fdwhandler.18`).
- [Structured evidence](../data/evidence/hv000.json) — fixed sources and bounded call-scan result.