Fix PGRST205: Could not find the table in the schema cache

Postgres 15 · Supabase✓ code tested against a real database

TL;DR

The Data API doesn't know that table. Check the name and schema first (the hint often suggests the right one), make sure the schema is in the API's exposed schemas, and reload the cache with notify pgrst, 'reload schema'. Then grant the table, or the next error is 42501.

01 What the error says

response

{
  "code": "PGRST205",
  "message": "Could not find the table 'public.order' in the schema cache",
  "hint": "Perhaps you meant the table 'public.orders'"
}

The Data API (PostgREST) keeps a cache of the tables it can serve. HTTP 404 with PGRST205 means the table you asked for isn't in it. This is a different problem from RLS or grants: the request never reached the table.

02 The three causes

CAUSE 1 · most common

Wrong name or schema

A typo, a singular/plural mismatch, or a table that lives in another schema. Read the hint: it suggests the closest match.

CAUSE 2

The schema isn't exposed

Only schemas listed in the Data API settings (exposed schemas) are served. A table in app needs that schema added there, and the client must ask for it: supabase.schema('app').from('orders').

CAUSE 3

A stale cache

The table was just created or renamed and the cache hasn't caught up.

03 Reload the schema cache

SQL editor

notify pgrst, 'reload schema';

04 Right after: grants and RLS

Once the API finds the table, the role still needs privileges. Without them the error changes to permission denied for schema app or permission denied for table orders (42501). Set it up in one migration, with RLS on:

migration.sql

grant usage on schema app to authenticated;
alter table app.orders enable row level security;
create policy "owner reads" on app.orders for select to authenticated
  using (user_id = (select auth.uid()));
grant select on app.orders to authenticated;

Exposing a schema makes every table in it reachable through the API, so each one needs RLS and only the grants it should have. More on the 42501 that follows.

◆ FREE · MIT · npm + GitHub Action

Catch this before it ships

airlock-rls is a CI gate that fails your build when a table ships exposed or a policy is permissive: the same class of bug, caught in CI against a database with your migrations applied, before it reaches prod.

npx airlock-rls→

Or start from nextjs-supabase-starter : auth + a table with RLS + an isolation test, so you start from a pattern that's already sealed.

FREE PDF

Grab the Supabase RLS cheat sheet

The golden rules, the footguns that leak in prod, correct policy snippets, and the isolation test — on one page.

FAQ

I reloaded the cache and still get PGRST205. Why?

Then it's the name or the schema. Check the hint in the response, and confirm the schema is in the exposed schemas list and that the client calls .schema() for non-public schemas.

Should I expose a private schema to fix it?

Only if the API should serve its tables. Exposing a schema makes all of its tables reachable, so keep helper functions and internal tables in a schema that stays unexposed.