Guide
PGRST002: Could not query the database for the schema cache. Retrying.
How this guide was made: Written with AI assistance and checked against the sources linked on this page.
Updated
Short answer: PGRST002 is a 503 error from Supabase's data API. PostgREST, the service behind it, could not reach your database while it built its schema cache, the metadata about your tables and functions. Check that the database is running, check the Exposed Schemas setting, reload the schema cache, then contact Supabase support if the error stays.
What does "PGRST002" mean?
PGRST002 is an error from PostgREST, the service that turns your Supabase database tables into the REST API your app calls. Supabase lists it as HTTP 503 with the description "Could not connect with the database when building the schema cache" (Supabase: PostgREST error codes). PostgREST's own error reference gives the cause as "the PostgreSQL service not running" (PostgREST: Errors).
Your app shows the longer text, "Could not query the database for the schema cache. Retrying.", as quoted in a Supabase GitHub issue (supabase/supabase #50385).
PostgREST keeps a schema cache because "getting this metadata requires expensive queries" (PostgREST: Schema cache). When the cache cannot be built, REST requests fail with this 503. The error is about the connection between the API and the database. It is not a bad query in your code.
Which cause is it?
| What you see | Cause | Fix |
|---|---|---|
| The error on REST requests, while direct database connections still work | The Postgres service or its connection is down or not ready | Cause 1 |
Postgres logs show schema "<name>" does not exist | Exposed Schemas lists a schema that is not in the database | Cause 2 |
| The error started after you changed tables, functions or schemas | The schema cache is stale | Cause 3 |
| Still failing after the fixes above | No fix is documented in the sources we read; Supabase support has to look at it | Cause 4 |
1. The database service is down or not ready
PostgREST's error reference ties PGRST002 to "the PostgreSQL service not running" (PostgREST: Errors). The sibling connection codes are also 503s: PGRST000 covers an incorrect connection string or Postgres not running, and PGRST001 covers an internal connection error (Supabase: PostgREST error codes).
How to fix it
- Restart the project from the Supabase dashboard. In issue #50385 the reporter tried this first and the error stayed. Our suggestion: test again after the restart finishes.
- Test a direct connection to the database with your connection string. In issue #50385 the reporter found that direct database connections worked while REST requests returned PGRST002.
- If the direct connection fails too, the database itself is the problem. Go to Cause 4.
- If the direct connection works, the problem sits between the API and the database. Go to Cause 2, then Cause 3.
Source: PostgREST: Errors, supabase/supabase #50385
2. Exposed Schemas lists a schema that does not exist
A user report in Supabase's GitHub discussions traced PGRST002 to PostgREST looking for a schema that was not in the database. The Postgres log showed schema "eSOP" does not exist. A later reply says: "I got the same error by exposing schema that does not exist." The fix given in that reply is to check Project settings, then Data API, then Exposed Schemas (supabase discussion #38917). This is a user report, not a Supabase staff answer, so check the list yourself.
How to fix it
- Open Project settings, then Data API, then the Exposed Schemas list.
- Compare each name in the list with the schemas your database has. In the discussion, "eSOP" was the project name, not a schema, and no code referenced it.
- Remove any name your database does not have. Our suggestion: then test a REST request again.
- Our suggestion: check the database logs for
schema "<name>" does not exist. If that line stops appearing, the exposed schema was the cause.
Source: supabase discussion #38917
3. The schema cache is stale
PostgREST says that changes to the database can leave the cache out of date, and that "to not let the schema cache go stale ... you need to reload it." The reload command is NOTIFY pgrst, 'reload schema' (PostgREST: Schema cache). PostgREST ties this reload to its schema cache errors. PGRST002 is in the connection group, so the reload may not fix it. In issue #50385 the reporter ran the reload and the error stayed.
How to fix it
- Run this SQL against your database:
NOTIFY pgrst, 'reload schema';
- Our suggestion: test a REST request again.
- If the error stays, go to Cause 4.
Source: PostgREST: Schema cache, supabase/supabase #50385
4. The error continues after the fixes above
No Supabase page we read gives a fix for PGRST002 itself. In issue #50385, the reporter's restart and schema reload did not clear the error. A Supabase collaborator replied: "You should contact support to get this one looked at." and gave support@supabase.com. The issue was closed the same day with no fix in the thread (supabase/supabase #50385).
How to fix it
- Our suggestion: note your project reference, the time of a failing request, and the exact PGRST002 response.
- Add what you found in Cause 1 (whether direct connections work) and the Exposed Schemas list from Cause 2.
- Send this to support@supabase.com.
Source: supabase/supabase #50385
How do I check it's fixed?
- Our suggestion: make a REST request to a table your app uses, with your project's API key.
- Expect a normal response. The response should not be a 503 with PGRST002.
- Our suggestion: load the page in your live app that failed. Check that its data shows.
- If the 503 comes back, the cause is in Cause 4.
FAQ
Is PGRST002 the same as PGRST000 or PGRST001?
No. PostgREST's connection group lists PGRST000 as a 503 for an incorrect connection string or Postgres not running, PGRST001 as a 503 for an internal connection error, and PGRST003 as a 504 timeout waiting for a pooled connection (Supabase: PostgREST error codes). PGRST002 is the schema cache case.
Does PGRST002 mean my code is wrong?
The error comes from building the schema cache, a step in the API's connection to the database. It is not a query error in your code. Supabase lists it as a connection error (Supabase: PostgREST error codes).
Does the reload command fix PGRST002?
PostgREST documents the reload for a stale cache (PostgREST: Schema cache). The docs do not say it fixes PGRST002. In the one report we read, the reload did not fix it (supabase/supabase #50385).
Can a restart fix it?
The docs we read do not say a restart clears PGRST002. In issue #50385, a restart did not fix it.
Related guides
- Supabase PGRST106: the fix
- Supabase: could not find the table in the schema cache
- Supabase database error querying schema
Sources (official documentation)
- Supabase: PostgREST error codes
- PostgREST: Errors
- PostgREST: Schema cache
- supabase discussion #38917 (user report, Supabase org GitHub)
- supabase/supabase issue #50385 (user report, Supabase GitHub)
Last checked: 17 November 2026.
VibeFix is independent. Supabase is a trademark of its owner.
More guides · Shopify store accessibility · About · Your privacy choices