How to fix HV005: fdw_column_name_not_found in PostgreSQL

PostgreSQLINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 97 views

PostgreSQL raises HV005 when a foreign-data wrapper tries to bind a local column that no longer exists on the remote object, which typically happens after the remote schema change or a mis-specified fdw_column_name mapping. Aligning the foreign table definition with the remote table (or dropping the dead column) restores the column metadata and lets the query run again.

Quick fix

Fixes HV005: fdw_column_name_not_found

-- Show the local column map and id, fdw_column_name options:
\d+ foreign_schema.remote_table

-- Or query the information schema for the FDW mapping:
SELECT column_name, foreign_column_name
FROM information_schema.foreign_table_columns
WHERE foreign_table_schema = 'foreign_schema'
  AND foreign_table_name = 'remote_table';
  1. Inspect the local foreign table definition
  2. Confirm the remote table actually exposes the column
  3. Update the foreign table to match the remote schema
  4. Re-import or recreate the foreign table after a large schema change
postgresql — error
-- Show the local column map and id, fdw_column_name options:
\d+ foreign_schema.remote_table
-- Or query the information schema for the FDW mapping:
SELECT column_name, foreign_column_name
FROM information_schema.foreign_table_columns
WHERE foreign_table_schema = 'foreign_schema'
  AND foreign_table_name = 'remote_table';
HV005: fdw_column_name_not_found

What this error means

HV005 is part of the SQL/MED error class that PostgreSQL uses whenever a foreign-data wrapper (FDW) cannot locate a column that the planner believes should exist on the remote side. The FDW layer builds remote queries by walking the columns defined on the local FOREIGN TABLE, which includes both the local column name and the optional remote name supplied via the fdw_column_name option. When the remote server no longer exposes that column—because it was renamed, dropped, or never existed—the FDW raises HV005 before it ever sends the query across the wire. This safeguard keeps PostgreSQL from sending invalid requests to the remote server and allows you to react by reconciling the local foreign table definition with whatever the remote catalog actually contains.

Typical symptoms

  • Any SELECT/INSERT/UPDATE against a foreign table fails immediately with "HV005: fdw_column_name_not_found" and the query plan never reaches the remote node.
  • Views, functions, or rules that depend on the foreign table break after you rename or drop a column on the remote server.
  • IMPORT FOREIGN SCHEMA or ALTER FOREIGN TABLE statements that touch the stale column return the same HV005 error.
  • Logs mention the fdw_column_name_not_found condition while the rest of the SQL looks valid.

Common causes

  1. The remote table lost the column (renamed or dropped) but the local foreign table still declares it.
  2. LIMIT/EXCEPT filters during IMPORT FOREIGN SCHEMA left a column out, yet your queries still reference it.
  3. An fdw_column_name option references a column that the remote server no longer provides.
  4. Quoting/case-sensitivity issues cause the FDW to look for a different name than the one exposed remotely.
  5. The foreign table was pointed at a different remote object that lacks the expected column.

How to fix "HV005: fdw_column_name_not_found"

1Inspect the local foreign table definition

Use psql to describe the foreign table and compare its columns with the ones you expect to query.

sql
-- Show the local column map and id, fdw_column_name options:
\d+ foreign_schema.remote_table

-- Or query the information schema for the FDW mapping:
SELECT column_name, foreign_column_name
FROM information_schema.foreign_table_columns
WHERE foreign_table_schema = 'foreign_schema'
  AND foreign_table_name = 'remote_table';

If the column mentioned in the HV005 error is listed here, PostgreSQL is trying to send it to the remote server even though the remote copy does not have it.

2Confirm the remote table actually exposes the column

Connect directly to the remote server (or reuse the same server connection) and list the remote columns. This confirms whether the column exists and how it is spelled/cased.

sql
\c - foreign_server_db
SELECT column_name
FROM information_schema.columns
WHERE table_schema = 'public'
  AND table_name = 'actual_table_name';

If the column is missing, you now know why FDW raised HV005; if it exists under another name, note the exact spelling.

3Update the foreign table to match the remote schema

Drop or rename the stale column on the foreign table, or add a new column that maps to the current remote column name. When you alter a foreign table, you can supply fdw_column_name so PostgreSQL knows the remote identifier.

sql
ALTER FOREIGN TABLE foreign_schema.remote_table
  DROP COLUMN missing_column;

ALTER FOREIGN TABLE foreign_schema.remote_table
  ADD COLUMN new_column text
    OPTIONS (fdw_column_name 'real_remote_name');

If multiple columns changed, repeat this step until the local definition mirrors what the remote catalog reports.

4Re-import or recreate the foreign table after a large schema change

When the remote table underwent wholesale changes, it can be easier to drop the foreign table and re-run IMPORT FOREIGN SCHEMA so PostgreSQL rebuilds the column list from scratch.

sql
DROP FOREIGN TABLE IF EXISTS foreign_schema.remote_table;
IMPORT FOREIGN SCHEMA public
  LIMIT TO (remote_table)
  FROM SERVER remote_server
  INTO foreign_schema;

This always pulls the current column set. Remember to reapply any custom column-level options, permissions, or triggers afterward.

Advanced notes

HV005 corresponds to SQL/MED error fdw_column_name_not_found, which any SQL/MED-compliant FDW can raise when the remote descriptor does not match the local one. PostgreSQL caches the column metadata for foreign tables, so you must issue ALTER FOREIGN TABLE or re-import the schema whenever the remote DDL changes; otherwise the planner refuses to send the invalid column list and surfaces HV005 instead.

Because this check runs before opening the remote connection, you never incur a network round trip for a column that is guaranteed to be missing, which protects the remote server from unnecessary work.

Frequently asked questions

What does "HV005: fdw_column_name_not_found" mean?
HV005 is part of the SQL/MED error class that PostgreSQL uses whenever a foreign-data wrapper (FDW) cannot locate a column that the planner believes should exist on the remote side. The FDW layer builds remote queries by walking the columns defined on the local FOREIGN TABLE, which includes both the local column name and the optional remote name supplied via the fdw_column_name option. When the remote server no longer exposes that column—because it was renamed, dropped, or never existed—the FDW raises HV005 before it ever sends the query across the wire.
How do I fix "HV005: fdw_column_name_not_found"?
PostgreSQL raises HV005 when a foreign-data wrapper tries to bind a local column that no longer exists on the remote object, which typically happens after the remote schema change or a mis-specified fdw_column_name mapping. Aligning the foreign table definition with the remote table (or dropping the dead column) restores the column metadata and lets the query run again.
What causes "HV005: fdw_column_name_not_found"?
The remote table lost the column (renamed or dropped) but the local foreign table still declares it. LIMIT/EXCEPT filters during IMPORT FOREIGN SCHEMA left a column out, yet your queries still reference it. An fdw_column_name option references a column that the remote server no longer provides.
Is the "HV005: fdw_column_name_not_found" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading