supabase-common-errors

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".

インストールへ移動

リポジトリ: jeremylongshore/tons-of-skills-marketplace
ソースの最終更新活動: 2026年8月19日 12:13
検出された SKILL.md の言語: 英語
スター: 2,677
フォーク: 392

インストール方法

デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。

ソースファイルを確認

インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。

検索に戻るインストールに戻る

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

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()

Code	HTTP	Meaning	Root Cause	Fix
`PGRST301`	401	JWT expired or invalid	`SUPABASE_ANON_KEY` is wrong, or the user session expired	Verify `SUPABASE_ANON_KEY` matches the project; call `supabase.auth.refreshSession()`
`PGRST302`	401	Missing Authorization header	Client created without a key, or middleware stripped the header	Pass `SUPABASE_ANON_KEY` to `createClient()`; check proxy/CDN config
`PGRST116`	406	No rows returned for `.single()`	Query matched 0 rows but `.single()` expects exactly 1	Use `.maybeSingle()` for optional lookups, or check filters
`PGRST200`	400	Invalid query parameters	Malformed filter, bad operator, or invalid column reference	Check filter syntax: `.eq('col', val)` not `.eq('col = val')`
`PGRST204`	400	Column not found	Column name doesn't exist in the table or view	Verify column exists with `supabase gen types typescript`; check for typos
`PGRST000`	503	Connection pool exhausted	Too many concurrent connections from serverless functions	Enable pgBouncer (Supavisor) in project settings; reduce connection count

Code	Meaning	Root Cause	Fix
`42501`	RLS policy violation	Row-level security is blocking the operation for this user	Add or fix the RLS policy; test with service role to confirm
`23505`	Unique constraint violation	INSERT/UPDATE conflicts with an existing row	Use `.upsert({ onConflict: 'column' })` or check existence first
`23503`	Foreign key violation	Referenced row doesn't exist in the parent table	Insert the parent row first, or check the foreign key value
`42P01`	Table or relation doesn't exist	Migration not applied, or wrong schema	Run `supabase db push`; verify schema with `\dt` in SQL Editor
`42703`	Column doesn't exist	Schema out of sync with code	Regenerate types: `supabase gen types typescript --local > types/supabase.ts`
`57014`	Query cancelled (statement timeout)	Query took longer than `statement_timeout`	Add indexes; simplify the query; increase timeout in `postgresql.conf`

// BAD — throws PGRST116 when the user has no profile row
const { data: profile } = await supabase
  .from('profiles').select('*').eq('user_id', userId).single()

// GOOD — returns null instead of erroring
const { data: profile, error } = await supabase
  .from('profiles').select('*').eq('user_id', userId).maybeSingle()

if (!profile) {
  await supabase.from('profiles').insert({ user_id: userId, display_name: 'New User' })
}