Debugging guide

Debug by evidence, not by guessing. A Supabase error almost always surfaces at one layer but originates at another, so the fastest path to a fix is finding where the problem is, not pattern-matching the symptom. Retrying a failed request rarely helps; isolating the layer does.

Follow these debugging steps

Work through these steps in order, skipping straight to a fix before you have evidence for the cause is the most common way to waste time on a bug.

1. Reproduce the issue and read the error precisely. Capture the exact status code, the error code, and the full message, not a paraphrase. A 401 is not a 403; PGRST002 is not PGRST106; a Postgres SQLSTATE such as 42501, 42P01, or 23505 points at the exact failure. The precise error is your strongest clue. If you're using supabase-js, remember that errors are returned, not thrown, check the error field in the { data, error } response object. Make sure your code inspects error — a swallowed error is why many bugs look like "nothing happened".
2. Locate the failing layer. Use the request stack below. The status code and error code usually name the layer for you.
3. Gather evidence for that layer. Query its logs, run the security and performance advisors, and inspect the schema. Logs are the primary tool, and the layer you identified in the previous step tells you which log source to query. See Read the logs below.
4. Isolate the cause using the troubleshooting guide for that layer (see Find the guide for your symptom below). Confirm your hypothesis against the evidence before you act. Most Supabase issues trace back to a small, known set of causes, and the guide explains how to tell them apart.
5. Apply the fix, then verify. Re-run the exact operation that failed and confirm it now succeeds, and that the corresponding log line is clean. A fix you haven't re-run is still a guess. If a couple of attempts don't resolve it, stop and gather more evidence rather than repeating the same change.

Check the request stack

A request from a client passes through several layers before it reaches your data. Errors propagate upward, so the layer that reports an error is often not the layer that caused it.

Knowing the shape of the stack is what makes isolating the layer possible.

Client (supabase-js / SSR)
  → Edge / API gateway → edge_logs (HTTP status, routing, rate limits)
      The gateway routes each request to ONE of these services. They run in parallel,
      not as a chain:
      ├→ PostgREST (Data API)  → postgrest_logs (low-signal; PGRST* evidence lives in edge_logs and postgres_logs)
      ├→ GoTrue (Auth)         → auth_logs      (login, JWT, OAuth, email)
      ├→ Storage API           → storage_logs   (uploads, object access)
      └→ Realtime              → realtime_logs  (channels, presence, broadcast)
  PostgREST, GoTrue, and Storage each reach the database independently:
  → Supavisor (connection pooler) → supavisor_logs (pooling, timeouts)
  → Postgres (SQL, RLS, triggers) → postgres_logs  (SQLSTATE, RLS, functions)

Edge Functions sit outside this stack and log separately: function_edge_logs for the HTTP request to the function, and function_logs for console output from inside it.

A permission error or an unexpectedly empty result at the API layer is often a Postgres row-level security or privilege problem one layer down, though filters, authentication, query shape, or a stale schema cache can produce the same symptom. When in doubt, trace toward the database.

Read the logs

Once you know the layer, query that layer's log source directly rather than scanning everything. Pick one source, bound the time window, and select only the fields you need.

When a query comes up empty, widen along an anchor, such as a timestamp, request ID, or error code, to follow the same request into the adjacent source (for example from edge_logs into postgres_logs) instead of broadening into an unfiltered scan.

A wide, unfiltered query across every source buries the one line you need and, on paid projects, costs more in scanned data.

The Logging guide covers the Logs Explorer, the available log sources, and how to write queries against them.

Find the guide for your symptom

Match your symptom to a layer, confirm it against that layer's logs, then open the troubleshooting guide for the specific cause and fix. If a symptom could fit two layers (for example, an auth call failing with what looks like an RLS error), start with the layer closest to the database.

Supabase updates these troubleshooting guides continuously, so treat this table as a starting point rather than the final word: if your exact symptom isn't listed, search the troubleshooting index for the error string.

For query performance and schema-design questions such as indexing, EXPLAIN, N+1 queries, or partitioning, see the Postgres guides.

Debugging is complete only once you've re-run the failing operation, confirmed it succeeds, and checked that the layer's logs show a clean result.

Per-product debugging

Each Supabase product has its own debugging resources. Use these as a starting point when the error originates in a specific service.

• Database — Debugging and monitoring
• Auth — Error codes
• Storage — Debugging
• Edge Functions — Local debugging