supabase-common-errors

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 <[e-mail]>
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  // data is null here — do not touch it
}
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.