HV001 — fdw_out_of_memory

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

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Foreign Data Wrapper Error (SQL/MED)
condition name: fdw_out_of_memory
lang: en
sqlstate: HV001

Definition PG 18

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.

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 is the generic FDW condition. HV002 is a missing wrapper parameter. 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 — definition, SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba.
postgres_fdw/option.c — option discovery and allocation paths.
dblink.c — dblink option path.
Structured evidence — exact message variants and source hashes.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read the fixed errcodes row and macro.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "HV001 is fdw_out_of_memory in SQL/MED Class HV."
}

claims · postgres-fdw-options

{
  "claim_id": "postgres-fdw-options",
  "limits": "The source assumes allocation failure for PQconndefaults; it does not prove global backend memory exhaustion.",
  "method": "Read option.c lines 313-341 and its adjacent failure comments.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.postgres_fdw.option.18.6"
  ],
  "statement": "postgres_fdw reports HV001 when PQconndefaults returns null and when allocation of its copied option array fails."
}

claims · dblink-options

{
  "claim_id": "dblink-options",
  "limits": "dblink is a separate contrib client API, not an FDW callback implementation.",
  "method": "Read dblink.c lines 1968-1974 and 2904-2910.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.dblink.18.6"
  ],
  "statement": "dblink reports HV001 when PQconndefaults returns null in two connection-option paths."
}

messages · postgres_fdw_pqconndefaults

{
  "limits": "",
  "message_id": "postgres_fdw_pqconndefaults",
  "path": "contrib/postgres_fdw/option.c:317-319",
  "position": 0,
  "raw": {
    "detail": "Could not get libpq's default connection options.",
    "id": "postgres_fdw_pqconndefaults",
    "message": "out of memory",
    "path": "contrib/postgres_fdw/option.c:317-319",
    "severity": "ERROR",
    "source_ids": [
      "src.postgres_fdw.option.18.6"
    ],
    "sqlstate": "HV001"
  },
  "severity": "ERROR",
  "sources": [
    "src.postgres_fdw.option.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "out of memory",
      "position": 0,
      "role": "observed",
      "template": "out of memory"
    },
    {
      "kind": "detail",
      "literal": "Could not get libpq's default connection options.",
      "position": 1,
      "role": "observed",
      "template": "Could not get libpq's default connection options."
    }
  ]
}

messages · postgres_fdw_malloc

{
  "limits": "",
  "message_id": "postgres_fdw_malloc",
  "path": "contrib/postgres_fdw/option.c:340-341",
  "position": 1,
  "raw": {
    "id": "postgres_fdw_malloc",
    "message": "out of memory",
    "path": "contrib/postgres_fdw/option.c:340-341",
    "severity": "ERROR",
    "source_ids": [
      "src.postgres_fdw.option.18.6"
    ],
    "sqlstate": "HV001"
  },
  "severity": "ERROR",
  "sources": [
    "src.postgres_fdw.option.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "out of memory",
      "position": 0,
      "role": "observed",
      "template": "out of memory"
    }
  ]
}

messages · dblink_pqconndefaults

{
  "limits": "",
  "message_id": "dblink_pqconndefaults",
  "path": "contrib/dblink/dblink.c:1972-1974; 2908-2910",
  "position": 2,
  "raw": {
    "detail": "Could not get libpq's default connection options.",
    "id": "dblink_pqconndefaults",
    "message": "out of memory",
    "path": "contrib/dblink/dblink.c:1972-1974; 2908-2910",
    "severity": "ERROR",
    "source_ids": [
      "src.dblink.18.6"
    ],
    "sqlstate": "HV001"
  },
  "severity": "ERROR",
  "sources": [
    "src.dblink.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "out of memory",
      "position": 0,
      "role": "observed",
      "template": "out of memory"
    },
    {
      "kind": "detail",
      "literal": "Could not get libpq's default connection options.",
      "position": 1,
      "role": "observed",
      "template": "Could not get libpq's default connection options."
    }
  ]
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt"
}

sources · src.postgres_fdw.option.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/postgres_fdw/option.c",
  "position": 1,
  "sha256": "880fd16c3e5cbc56733d1292ffdcc9b0f6cb1e17e72c90e9afa4e359239dc314",
  "source_id": "src.postgres_fdw.option.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/postgres_fdw/option.c"
}

sources · src.dblink.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/dblink/dblink.c",
  "position": 2,
  "sha256": "e4cfaec3a0a1e5d23fded584725e0f6cf7a17321ad99e5fe046e8b7f97416f15",
  "source_id": "src.dblink.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/dblink/dblink.c"
}

sources · src.calls.REL_18_6

{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "raw/calls/REL_18_6.jsonl",
  "position": 3,
  "sha256": "9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf",
  "source_id": "src.calls.REL_18_6",
  "tag": "",
  "url": ""
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:661c3d329f17aa7387ad938cf878cfc4b592648e79cdf748ea7b624fa018c236

Text language: en · english-manuals:661c3d329f17aa7387ad938cf878cfc4b592648e79cdf748ea7b624fa018c236