HV000 — fdw_error

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.

Meaning and scope

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

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

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

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

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

Compare HV001 — fdw_out_of_memory, HV002 — fdw_dynamic_parameter_value_needed, and HV00B — fdw_invalid_handle. Remote server conditions must be interpreted using the remote system’s own SQLSTATE and diagnostics.

Sources

• errcodes.txt — fixed PostgreSQL 18.6 definition (src.errcodes.18.6, SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba).
• fdwapi.h — callback boundary (src.fdwapi.18.6).
• nodeForeignscan.c — executor callback dispatch (src.nodeforeignscan.18.6).
• FDW callback documentation — callback responsibilities and error boundary (doc.fdwhandler.18).
• Structured evidence — fixed sources and bounded call-scan result.