supabase-common-errors
Troubleshooting guide for identifying and resolving Supabase error codes.
Install
mkdir -p .claude/skills/supabase-common-errors && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/1228" && unzip -o skill.zip -d .claude/skills/supabase-common-errors && rm skill.zipInstalls to .claude/skills/supabase-common-errors
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Diagnose and fix Supabase errors across PostgREST, PostgreSQL, Auth,Key capabilities
- →Capture Supabase error objects from SDK calls.
- →Identify the error layer and code (PostgREST, PostgreSQL, Auth, Storage).
- →Apply fixes for common errors like expired JWTs or RLS violations.
- →Verify fixes by re-running the original operation.
- →Implement guard code to prevent null-data bugs.
How it works
The skill provides a workflow to capture Supabase error objects, classify them by layer and code, and apply documented fixes to resolve issues.
Inputs & outputs
When to use supabase-common-errors
- →Resolving PostgREST 403 errors
- →Debugging RLS policy failures
- →Fixing auth token errors
About this skill
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 — database queries return { data, error }; other SDK services have their own result, callback, and exception contracts.
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-jsinstalled (npm install @supabase/supabase-js)SUPABASE_URLand a publishable/anon key configured; normal request clients use verified user identity and RLS- 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
Supabase database queries return a { data, error } result. 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`);
Do not diagnose the installed SDK version solely from an undefined property. Check which service/method produced the result, its documented shape, and the locked dependency version. Realtime subscriptions and Python clients differ.
Step 2 — Identify the Error Layer and Code
Match the code prefix to its subsystem, then look it up in the Error Handling tables below:
PGRST*→ PostgREST (API gateway: JWT, query parsing, schema)- 5-character SQLSTATE (e.g.
42501,23505) → PostgreSQL engine (RLS, constraints, migrations) AuthApiError→ Auth service (credentials, confirmation, token expiry)StorageApiError→ Storage service (bucket, RLS onstorage.objects, size limits)
A missing code needs service-specific inspection: 401 can reflect invalid user credentials or a missing bearer identity, and 500 has multiple possible causes. Status alone does not prove a wrong project key or failing SQL function. A paste-ready diagnoseSupabaseError() classifier is in the walkthrough.
Step 3 — Apply the Fix and Verify
Apply the fix from the matching Error Handling table, then re-run the original operation to confirm. Common recoveries:
- For
PGRST301, verify the JWT/project/session configuration; it means the JWT cannot be decoded or is invalid. Use the Auth session recovery workflow only when appropriate, not an automatic retry loop. - For
42501, inspect verified user identity, grants, and RLS under that identity. It means insufficient privilege, not necessarily RLS. Do not bypass the user boundary with a service-role client in the request path. - After a migration, reload the PostgREST schema cache (an authorized SQL session using
NOTIFY pgrst, 'reload schema').
Full before/after fix code for both cases is in the walkthrough.
Output
Deliverables after applying this skill:
- Error identified by code and layer (PostgREST, PostgreSQL, Auth, Storage, Realtime)
- Root cause isolated using the diagnostic helper or manual code inspection
- Fix applied from the Error Handling table and verified against the original failing operation
- Guard code in place (
if (error)checks) preventing silent null-data bugs
Error Handling
The two most-cited layers are inline below. Auth, Storage, and Realtime tables are in the full error reference.
PostgREST API Errors (PGRST*)
| Code | HTTP | Meaning | Root Cause | Fix |
|---|---|---|---|---|
PGRST301 | 401 | JWT cannot be decoded or is invalid | Invalid token or mismatched configuration | Verify token/project/session through the appropriate Auth workflow; do not retry blindly |
PGRST302 | 401 | Bearer request absent while anonymous role disabled | Request lacks required identity | Verify authenticated bearer propagation and server configuration |
PGRST116 | 406 | Singular result has zero or multiple rows | Result does not satisfy exactly-one contract | Use .maybeSingle() for zero-or-one; correct multiple matches |
PGRST200 | 400 | Relationship/schema-cache mismatch | Embedded relationship absent or stale | Check foreign keys and embedding; refresh cache if appropriate |
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 | Database connection unavailable | Invalid database URI or database not running | Inspect service configuration and availability |
PGRST003 | 504 | Pool acquisition timed out | No pool connection became available | Inspect query load and pool capacity; apply bounded admission |
PostgreSQL Database Errors (SQLSTATE)
| Code | Meaning | Root Cause | Fix |
|---|---|---|---|
42501 | Insufficient privilege | Grants or RLS deny this identity | Review grants and policies with the actual authorized user |
23505 | Unique constraint violation | INSERT/UPDATE conflicts with an existing row | Review conflict semantics; .upsert(row, { onConflict: 'column' }) can overwrite data and needs authorization |
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 |
Examples
The most common failure — calling .single() on optional data — is inline below. Three more worked examples (upsert to dodge 23505, Realtime subscription error handling, and serverless pool exhaustion) are in the examples reference.
Handling .single() on optional data (PGRST116)
const { data: profile, error } = await supabase
.from('profiles')
.select('id, display_name')
.eq('user_id', userId)
.maybeSingle();
if (error) throw error;
if (!profile) {
// A successful zero-row read is not authorization to create an arbitrary profile.
// Present the application's separately authorized create-profile workflow.
}
Resources
- Full diagnostic walkthrough — every capture/classify/fix code block
- Complete error reference — Auth, Storage, and Realtime tables
- Worked examples — upsert, Realtime, serverless pooling
- Supabase JavaScript SDK Reference
- PostgREST Error Codes
- PostgreSQL Error Codes
- RLS Debugging Guide
- Supabase Realtime Troubleshooting
- Supabase Status Page
Next Steps
- Use
supabase-debug-bundleto generate a full diagnostic snapshot when errors persist after applying these fixes. - Use
supabase-security-basicsto audit your RLS policies and prevent42501errors proactively. - Use
supabase-known-pitfallsfor edge cases and SDK behavior that can cause subtle bugs. - Use
supabase-observabilityto set up logging and alerting so you catch errors before users report them.
Prerequisites
Limitations
- →A missing error code usually means the HTTP status is the signal.
- →Querying with .single() expects exactly one row.
- →Too many concurrent connections can exhaust the connection pool.
How it compares
This skill offers a structured diagnostic and resolution process for Supabase errors, which is more systematic than ad-hoc debugging.
Compared to similar skills
supabase-common-errors side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| supabase-common-errors (this skill) | 4 | 4mo | Review | Intermediate |
| data-safety-auditor | 3 | 11mo | No flags | Advanced |
| supabase-postgres-best-practices | 4 | 10mo | No flags | Intermediate |
| supabase-policy-guardrails | 3 | 4mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by jeremylongshore
View all by jeremylongshore →You might also like
data-safety-auditor
ananddtyagi
Comprehensive data safety auditor for Vue 3 + Pinia + IndexedDB + PouchDB applications. Detects data loss risks, sync issues, race conditions, and browser-specific vulnerabilities with actionable remediation guidance.
supabase-postgres-best-practices
davila7
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
supabase-policy-guardrails
jeremylongshore
Implement Supabase lint rules, policy enforcement, and automated guardrails. Use when setting up code quality rules for Supabase integrations, implementing pre-commit hooks, or configuring CI policy checks for Supabase best practices. Trigger with phrases like "supabase policy", "supabase lint", "supabase guardrails", "supabase best practices check", "supabase eslint".
supabase-known-pitfalls
jeremylongshore
Execute identify and avoid Supabase anti-patterns and common integration mistakes. Use when reviewing Supabase code for issues, onboarding new developers, or auditing existing Supabase integrations for best practices violations. Trigger with phrases like "supabase mistakes", "supabase anti-patterns", "supabase pitfalls", "supabase what not to do", "supabase code review".
supabase-incident-runbook
jeremylongshore
Execute Supabase incident response procedures with triage, mitigation, and postmortem. Use when responding to Supabase-related outages, investigating errors, or running post-incident reviews for Supabase integration failures. Trigger with phrases like "supabase incident", "supabase outage", "supabase down", "supabase on-call", "supabase emergency", "supabase broken".
backend-dev
marmelab
Coding practices for backend development in Atomic CRM. Use when deciding whether backend logic is needed, or when creating/modifying database migrations, views, triggers, RLS policies, edge functions, or custom dataProvider methods that call Supabase APIs.