PGRST002: Could not query the database for the schema cache

PGRST002 means PostgREST is running but can't load its schema cache from Postgres. Until it can, every Data API request for that project fails.

What you see

HTTP 503 from any /rest/v1/ request:

{"code":"PGRST002","details":null,"hint":null,"message":"Could not query the database for the schema cache. Retrying."}

Auth and Storage for the same project may work or fail at the same time, depending on the cause.

Why it happens

PostgREST builds the schema cache at startup and after every reload schema notification. To do that it needs a working connection and a few catalog queries that finish in time. It reports PGRST002 and keeps retrying when:

• Postgres isn't accepting connections: it's restarting, or the whole instance is being resized or upgraded.
• No connection slots are left. One Postgres server serves every project on the instance, with max_connections=400 shared between them.
• A lock blocks the catalog queries. A long ALTER TABLE or other DDL holding an exclusive lock can stall the cache query.
• The catalog is very large: thousands of tables, views or functions make the cache query slow.

How to fix it

1. Wait a minute and retry. If the cause was a restart, PostgREST recovers by itself. Check your email for an instance down/recovered alert.

2. Count connections in Studio's SQL editor, if it can still connect:

   select datname, usename, count(*)
   from pg_stat_activity
   group by 1, 2
   order by 3 desc;
   

   If the total is close to 400, find what holds them. Usual suspects are an ORM with a large pool or serverless functions that open a connection per invocation. Close idle ones:

   select pg_terminate_backend(pid)
   from pg_stat_activity
   where datname = current_database()
     and usename = 'postgres'
     and state = 'idle'
     and state_change < now() - interval '10 minutes';
   

3. Look for blocking locks:

   select pid, pg_blocking_pids(pid) as blocked_by, state,
          now() - query_start as running_for, left(query, 80) as query
   from pg_stat_activity
   where cardinality(pg_blocking_pids(pid)) > 0;
   

   If a migration is holding everything up, let it finish or cancel it with select pg_cancel_backend(<pid>);. See blocked queries.

4. Once the database is healthy, force a fresh cache:

   notify pgrst, 'reload schema';
   

On SupaHost

Some events briefly take the database or the whole instance offline:

• Changing plan resizes the VM, which means a minute or two of downtime for every project.
• Automatic upgrades run in the maintenance window you pick, 03:00-05:00 UTC.
• Restoring a project stops that project's Auth, REST and Storage while the database is swapped. During a restore you'll see gateway errors rather than PGRST002.

There's no searchable log explorer in the dashboard. On Business you can read the Data API's recent log lines over SSH with sudo supahost-logs app-one rest. On other plans, run the SQL checks above and include the times you saw the errors in a support request.

Related

• Too many connections
• Connections and timeouts
• 520 and 5xx errors from the REST API
• PostgREST not seeing new tables (schema cache)