| name | supabase-common-errors |
| description | Diagnose and fix Supabase errors across PostgREST, PostgreSQL, Auth, Storage, and Realtime.
Use when encountering error codes like PGRST301, 42501, 23505, or auth failures.
Use when debugging failed queries, RLS policy violations, or HTTP 4xx/5xx responses.
Trigger with "supabase error", "fix supabase", "PGRST", "supabase 403", "RLS not working",
"supabase auth error", "unique constraint", "foreign key violation".
|
| allowed-tools | Read, Grep, Bash(curl:*), Bash(supabase:*), Bash(npx:*) |
| version | 1.53.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","supabase","debugging","errors","postgrest","rls","auth"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Supabase Common Errors
Overview
Diagnostic guide for Supabase errors across PostgREST (PGRST*), PostgreSQL (numeric codes), Auth, Storage, and Realtime. Identify the error layer, trace the root cause, and apply the correct fix โ every SDK call returns { data, error } where data is null when error exists.
The workflow is three steps: capture the error object, classify it by layer and code, then apply and verify the fix. Full step-by-step code lives in the diagnostic walkthrough; complete lookup tables are in the error reference.
Prerequisites
@supabase/supabase-js installed (npm install @supabase/supabase-js)SUPABASE_URL and SUPABASE_ANON_KEY (or SUPABASE_SERVICE_ROLE_KEY) configured- Access to Supabase Dashboard (for log inspection and SQL Editor)
- Supabase CLI installed for local development (
npx supabase --version)
Instructions
Step 1 โ Capture the Error Object
Every Supabase SDK call returns a { data, error } tuple. Never assume data exists โ always destructure and check error first, because data is null whenever error is set.
const { data, error } = await supabase.from('todos').select('*')
if (error) {
console.error(`[${error.code}] ${error.message}`)
return
}
console.log(`Found ${data.length} rows`)
If error is undefined rather than null, upgrade to @supabase/supabase-js@2.x. See for the full guard pattern.
