# PGRST002: Could not query the database for the schema cache

> What the PGRST002 503 error from the Data API means, the usual causes (database unavailable, connections exhausted, locks) and how to check each one on SupaHost.

Source: https://supahost.app/kb/pgrst002-schema-cache · Updated 2026-11-11

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:

```json
{"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:

   ```sql
   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:

   ```sql
   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**:

   ```sql
   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](/kb/blocked-queries).

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

   ```sql
   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](/kb/support-requests).

## Related

- [Too many connections](/kb/too-many-connections)
- [Connections and timeouts](/docs/database/connections-and-timeouts)
- [520 and 5xx errors from the REST API](/kb/520-errors)
- [PostgREST not seeing new tables (schema cache)](/kb/postgrest-schema-cache)