PostgreSQL Error 42P01: Undefined Table

Quick Answer

List tables with \dt or information_schema.tables to confirm the name. If that does not apply, schema-qualify the table (schema.table) to avoid search_path ambiguity — the full checklist is below.

Error Code

SQLSTATE: 42P01
Official name: Undefined Table
System name: undefined_table
Service: PostgreSQL

What does this error mean?

The referenced table does not exist in the current schema search path.

Exact Error Messages

You may see this error reported as one of the following messages:

• relation "users" does not exist
• there is no unique constraint matching given keys for referenced table
• no matching unique or primary key for this column-list

Common Causes

• Misspelling the table name or using the wrong case
• Querying a table in the wrong schema due to search_path
• Table created in a transaction that was rolled back
• Connecting to a different database than expected

How to Fix

1. List tables with \dt or information_schema.tables to confirm the name
2. Schema-qualify the table (schema.table) to avoid search_path ambiguity
3. Check that migrations ran and committed in the target database
4. Verify the connection string points to the right database

Example Scenario

A fresh deployment runs SELECT * FROM orders before the migration that creates the table has been applied. PostgreSQL answers SQLSTATE 42P01: relation "orders" does not exist. The same error fires when the table lives in a non-public schema that is not on your search_path, or when you connected to a different database than you thought (common with Docker/CI where the default DB is postgres).

Diagnostic Commands

Run these to confirm the cause before applying a fix — each command answers a specific question.

SELECT current_database(), current_schema,
       current_setting('search_path');

SELECT schemaname, tablename FROM pg_tables
WHERE tablename ILIKE '%orders%';

Decision Guide

Table missing entirely?
├─ migration never ran → apply it (prisma migrate deploy / flyway migrate)
└─ wrong environment/database → fix the connection string

Table exists but in another schema?
├─ reference it qualified: myschema.orders
└─ or add the schema to search_path

Table created moments ago and still 42P01?
└─ in Supabase/PostgREST: NOTIFY pgrst, 'reload schema';
   the API layer caches the schema separately

Code Examples

SELECT schemaname, tablename
FROM pg_tables
WHERE tablename ILIKE '%order%';

Framework-Specific Fixes

class Meta:
    db_table = 'orders'  # match exactly

class Order(Base):
    __tablename__ = 'orders'

const { error } = await supabase.from('orders').select('*')
// verify table name + schema in Dashboard

You Might Also Like

Frequently Asked Questions

Recommended Tools

Recommendations are editorial — DB Error Reference takes no payment or affiliate fees for tool listings.

Official Sources

This page is based on the official PostgreSQL documentation linked below and adds practical troubleshooting guidance on top.

• PostgreSQL Error Codes (Appendix A)official
• Schema Search Pathofficial