VibeFix

Guide

PGRST002: Could not query the database for the schema cache. Retrying.

Published by Yosef D., founder of VibeFix

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.

Get it fixed: a free check first confirms the problem on your live app, usually in 4 to 10 minutes.

Free. No account needed. It usually takes 4 to 10 minutes.

Want it fixed? For Lovable apps or code on GitHub, our AI agent fixes it in your code for $79 and tests your live app again. If we can't complete your re-check, you get your money back.

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 seeCauseFix
The error on REST requests, while direct database connections still workThe Postgres service or its connection is down or not readyCause 1
Postgres logs show schema "<name>" does not existExposed Schemas lists a schema that is not in the databaseCause 2
The error started after you changed tables, functions or schemasThe schema cache is staleCause 3
Still failing after the fixes aboveNo fix is documented in the sources we read; Supabase support has to look at itCause 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

  1. 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.
  2. 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.
  3. If the direct connection fails too, the database itself is the problem. Go to Cause 4.
  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

  1. Open Project settings, then Data API, then the Exposed Schemas list.
  2. 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.
  3. Remove any name your database does not have. Our suggestion: then test a REST request again.
  4. 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

  1. Run this SQL against your database:
NOTIFY pgrst, 'reload schema';
  1. Our suggestion: test a REST request again.
  2. 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

  1. Our suggestion: note your project reference, the time of a failing request, and the exact PGRST002 response.
  2. Add what you found in Cause 1 (whether direct connections work) and the Exposed Schemas list from Cause 2.
  3. Send this to support@supabase.com.

Source: supabase/supabase #50385

How do I check it's fixed?

  1. Our suggestion: make a REST request to a table your app uses, with your project's API key.
  2. Expect a normal response. The response should not be a 503 with PGRST002.
  3. Our suggestion: load the page in your live app that failed. Check that its data shows.
  4. 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

Sources (official documentation)

Last checked: 17 November 2026.

VibeFix is independent. Supabase is a trademark of its owner.

More guides · Shopify store accessibility · About · Your privacy choices