# HV001 — fdw_out_of_memory

> PostgreSQL SQLSTATE HV001 reports an FDW-side allocation failure. PostgreSQL's bundled dblink and postgres_fdw paths use it while obtaining libpq connection options.
---

# HV001 — fdw_out_of_memory

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

`HV001` is the SQL/MED condition for an FDW-side out-of-memory failure. In PostgreSQL 18.6, the bundled `postgres_fdw` and `dblink` implementations use it when `PQconndefaults()` returns no option array, and `postgres_fdw` also uses it when its option copy cannot be allocated.

The fixed source messages are `out of memory`, optionally with detail `Could not get libpq's default connection options.` This is an `ERROR`; whether the remote operation ran is phase-specific.

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

| Field | Value |
| --- | --- |
| SQLSTATE | `HV001` |
| Condition | `fdw_out_of_memory` |
| 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_OUT_OF_MEMORY` |
| Aliases | `—` |

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

## Meaning and trigger paths {#meaning}

`postgres_fdw` calls `PQconndefaults()` while building its option list; a null result is treated as an allocation failure and reported with `HV001`. A later `malloc` for the copied options has the same code but only the primary message. `dblink` has two corresponding option-discovery paths. These are wrapper implementation details, not proof that every `HV001` means the backend allocator exhausted all memory.

## Messages and diagnostics {#messages}

The 18.6 source variants are:

- `ERROR: out of memory`, with detail `Could not get libpq's default connection options.` in `contrib/dblink/dblink.c:1972-1974`, `:2908-2910`, and `contrib/postgres_fdw/option.c:317-319`.
- `ERROR: out of memory` without detail in `contrib/postgres_fdw/option.c:340-341`.

Keep the function phase and wrapper name. The message is not a remote server response.

## Diagnosis {#diagnosis}

Capture SQLSTATE and all fields, then identify whether failure occurred while reading FDW/server options or while establishing a dblink/postgres_fdw connection. Inspect backend memory pressure, process limits, and the wrapper/library versions. If the detail names libpq defaults, first distinguish a `PQconndefaults()` allocation failure from a libpq installation or configuration problem; check the local library path/version only as supporting evidence before debugging the remote SQL.

## Response {#response}

Reduce concurrent memory pressure and check the backend process/container limits, then retry the same option-discovery operation only after the allocation failure is understood. If the server actually reports `53200`, follow that SQLSTATE's diagnostic; do not relabel a confirmed `HV001` merely because an allocation failed. For a write path, establish from the callback phase and remote logs whether any remote command was sent before retrying; `HV001` alone is not a whole-transaction retry signal.

## Versions {#versions}

The catalogue first observes `HV001` in 9.1.0 and retains it through 18.6 and 19 Beta 3. The 18.6 implementation paths and exact capitalization above are fixed to commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; older variants may differ.

## Related {#related}

[`HV000`](../hv000/) is the generic FDW condition. [`HV002`](../hv002/) is a missing wrapper parameter. [`53200`](../53200/) is the generic backend out-of-memory condition and should not be substituted without evidence that the backend, rather than the FDW path, raised the error.

## Sources {#sources}

- [`errcodes.txt`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L477) — definition, SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba`.
- [`postgres_fdw/option.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/postgres_fdw/option.c#L313-L341) — option discovery and allocation paths.
- [`dblink.c`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/dblink/dblink.c#L1968-L1974) — dblink option path.
- [Structured evidence](../data/evidence/hv001.json) — exact message variants and source hashes.