How to fix HV00R: fdw_table_not_found in PostgreSQL

PostgreSQLINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 96 views

PostgreSQL raises HV00R when a foreign-data wrapper cannot locate a referenced table on the remote server. This typically occurs when querying a foreign table that has been dropped, renamed, or never existed on the remote side. Verifying the remote table existence and updating the foreign table definition resolves this error.

Quick fix

Fixes HV00R: fdw_table_not_found

-- Show detailed foreign table information:
\d+ schema_name.foreign_table_name

-- Query system catalogs for FDW table mapping:
SELECT ft.ftoptions, s.srvname
FROM pg_foreign_table ft
JOIN pg_foreign_server s ON ft.ftserver = s.oid
WHERE ft.ftrelid = 'schema_name.foreign_table_name'::regclass;
  1. Verify the foreign table definition
  2. Check remote table existence
  3. Update or recreate the foreign table
  4. Verify FDW connection and permissions
postgresql — error
-- Show detailed foreign table information:
\d+ schema_name.foreign_table_name
-- Query system catalogs for FDW table mapping:
SELECT ft.ftoptions, s.srvname
FROM pg_foreign_table ft
JOIN pg_foreign_server s ON ft.ftserver = s.oid
WHERE ft.ftrelid = 'schema_name.foreign_table_name'::regclass;
HV00R: fdw_table_not_found

What this error means

HV00R is a SQL/MED error code that PostgreSQL uses when a foreign-data wrapper (FDW) cannot find a table referenced in a foreign table query. This error occurs during query planning when PostgreSQL attempts to validate that the remote table exists before sending queries across the wire. Foreign-data wrappers allow PostgreSQL to query data from external sources as if they were local tables. When you create a foreign table in PostgreSQL, it points to a table on a remote server. If that remote table is dropped, renamed, or otherwise becomes inaccessible, any query against the foreign table will fail with HV00R. This error serves as an early validation check, preventing PostgreSQL from sending queries to non-existent remote tables and providing clear feedback about the schema mismatch.

Typical symptoms

  • Queries against foreign tables fail immediately with "HV00R: fdw_table_not_found" error message.
  • Foreign table operations that previously worked suddenly start failing after remote schema changes.
  • CREATE FOREIGN TABLE or IMPORT FOREIGN SCHEMA statements reference tables that don't exist on the remote server.
  • The error occurs during query planning phase before any connection to the remote server is established.
  • Logs show table lookup failures followed by HV00R error code.

Common causes

  1. The remote table was dropped or renamed on the remote server but the local foreign table definition still references it.
  2. The foreign table was created with an incorrect table name or schema specification.
  3. IMPORT FOREIGN SCHEMA imported tables that were later removed from the remote server.
  4. Permissions on the remote server prevent the FDW from seeing the table.
  5. Network or connection issues cause the FDW to receive empty or incorrect catalog information.
  6. The remote server uses a different naming convention or case sensitivity than expected.

How to fix "HV00R: fdw_table_not_found"

1Verify the foreign table definition

Check the local foreign table definition to see what remote table it references.

sql
-- Show detailed foreign table information:
\d+ schema_name.foreign_table_name

-- Query system catalogs for FDW table mapping:
SELECT ft.ftoptions, s.srvname
FROM pg_foreign_table ft
JOIN pg_foreign_server s ON ft.ftserver = s.oid
WHERE ft.ftrelid = 'schema_name.foreign_table_name'::regclass;

This reveals the server name and options that define which remote table this foreign table points to.

2Check remote table existence

Connect directly to the remote server (using the same credentials as the FDW) to verify the table exists.

sql
-- For postgres_fdw connecting to another PostgreSQL instance:
SELECT schemaname, tablename
FROM pg_tables
WHERE schemaname = 'remote_schema'
  AND tablename = 'remote_table';

-- Check for case sensitivity issues:
SELECT schemaname, tablename
FROM pg_tables
WHERE schemaname ILIKE 'remote_schema'
  AND tablename ILIKE 'remote_table';

-- For other FDWs, use appropriate remote catalog queries
-- For MySQL FDW:
SHOW TABLES FROM remote_database LIKE 'remote_table';

If the table doesn't exist, you've found the root cause.

3Update or recreate the foreign table

If the remote table was renamed or moved, update the foreign table definition to point to the correct table.

sql
-- Drop and recreate the foreign table with correct remote table name:
DROP FOREIGN TABLE IF EXISTS schema_name.foreign_table_name;

CREATE FOREIGN TABLE schema_name.foreign_table_name (
  -- column definitions
)
SERVER remote_server
OPTIONS (table_name 'correct_remote_table');

-- Or use IMPORT FOREIGN SCHEMA to recreate multiple tables:
IMPORT FOREIGN SCHEMA remote_schema
  LIMIT TO (correct_remote_table)
  FROM SERVER remote_server
  INTO schema_name;

Make sure the column definitions match the remote table structure.

4Verify FDW connection and permissions

Check that the FDW user has permission to access the remote table.

sql
-- Test the FDW connection directly:
SELECT * FROM dblink(
  'dbname=remote_db host=remote_host user=fdw_user',
  'SELECT 1'
) AS t(test int);

-- For postgres_fdw, check user mapping:
SELECT * FROM pg_user_mappings
WHERE srvname = 'remote_server';

-- Ensure the remote user has SELECT permission on the table:
-- On remote server:
GRANT SELECT ON remote_schema.remote_table TO fdw_user;

Connection or permission issues can sometimes manifest as table not found errors.

5Refresh foreign table metadata cache

If the remote table exists but PostgreSQL still reports it as missing, refresh the FDW metadata cache.

sql
-- For postgres_fdw, refresh the foreign table cache:
ALTER FOREIGN TABLE schema_name.foreign_table_name
  OPTIONS (ADD refresh 'true');

-- Or disconnect and reconnect to force cache refresh:
-- Restart the PostgreSQL service or
-- Execute for each foreign table:
NOTIFY pg_fdw_refresh_cache;

-- Check if there are any pending schema changes:
SELECT * FROM pg_foreign_table
WHERE ftrelid = 'schema_name.foreign_table_name'::regclass;

Some FDWs cache table metadata which can become stale.

Advanced notes

HV00R corresponds to SQL/MED error fdw_table_not_found, which any SQL/MED-compliant FDW can raise when a referenced remote table cannot be located. This error typically occurs before any query execution, during the planning phase when PostgreSQL validates foreign table metadata.

Different FDWs may have different behaviors: some check table existence on every query, while others cache this information. The postgres_fdw extension, for example, caches foreign table metadata and may need explicit refresh when remote schemas change.

When troubleshooting HV00R, consider not only table existence but also schema/table name case sensitivity, search path settings on the remote server, and any schema name mapping options specified in the foreign table definition.

Frequently asked questions

What does "HV00R: fdw_table_not_found" mean?
HV00R is a SQL/MED error code that PostgreSQL uses when a foreign-data wrapper (FDW) cannot find a table referenced in a foreign table query. This error occurs during query planning when PostgreSQL attempts to validate that the remote table exists before sending queries across the wire. Foreign-data wrappers allow PostgreSQL to query data from external sources as if they were local tables.
How do I fix "HV00R: fdw_table_not_found"?
PostgreSQL raises HV00R when a foreign-data wrapper cannot locate a referenced table on the remote server. This typically occurs when querying a foreign table that has been dropped, renamed, or never existed on the remote side. Verifying the remote table existence and updating the foreign table definition resolves this error.
What causes "HV00R: fdw_table_not_found"?
The remote table was dropped or renamed on the remote server but the local foreign table definition still references it. The foreign table was created with an incorrect table name or schema specification. IMPORT FOREIGN SCHEMA imported tables that were later removed from the remote server.
Is the "HV00R: fdw_table_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