SU

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

Installs 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,
68 charsno explicit “when” trigger
Intermediate

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

You give it
A Supabase SDK call returning a { data, error } tuple.
You get back
Error identified by code and layer, root cause isolated, fix applied and verified, and guard code implemented.

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-js installed (npm install @supabase/supabase-js)
  • SUPABASE_URL and 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 on storage.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*)

CodeHTTPMeaningRoot CauseFix
PGRST301401JWT cannot be decoded or is invalidInvalid token or mismatched configurationVerify token/project/session through the appropriate Auth workflow; do not retry blindly
PGRST302401Bearer request absent while anonymous role disabledRequest lacks required identityVerify authenticated bearer propagation and server configuration
PGRST116406Singular result has zero or multiple rowsResult does not satisfy exactly-one contractUse .maybeSingle() for zero-or-one; correct multiple matches
PGRST200400Relationship/schema-cache mismatchEmbedded relationship absent or staleCheck foreign keys and embedding; refresh cache if appropriate
PGRST204400Column not foundColumn name doesn't exist in the table or viewVerify column exists with supabase gen types typescript; check for typos
PGRST000503Database connection unavailableInvalid database URI or database not runningInspect service configuration and availability
PGRST003504Pool acquisition timed outNo pool connection became availableInspect query load and pool capacity; apply bounded admission

PostgreSQL Database Errors (SQLSTATE)

CodeMeaningRoot CauseFix
42501Insufficient privilegeGrants or RLS deny this identityReview grants and policies with the actual authorized user
23505Unique constraint violationINSERT/UPDATE conflicts with an existing rowReview conflict semantics; .upsert(row, { onConflict: 'column' }) can overwrite data and needs authorization
23503Foreign key violationReferenced row doesn't exist in the parent tableInsert the parent row first, or check the foreign key value
42P01Table or relation doesn't existMigration not applied, or wrong schemaRun supabase db push; verify schema with \dt in SQL Editor
42703Column doesn't existSchema out of sync with codeRegenerate types: supabase gen types typescript --local > types/supabase.ts
57014Query cancelled (statement timeout)Query took longer than statement_timeoutAdd 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

Next Steps

  • Use supabase-debug-bundle to generate a full diagnostic snapshot when errors persist after applying these fixes.
  • Use supabase-security-basics to audit your RLS policies and prevent 42501 errors proactively.
  • Use supabase-known-pitfalls for edge cases and SDK behavior that can cause subtle bugs.
  • Use supabase-observability to set up logging and alerting so you catch errors before users report them.

Prerequisites

@supabase/supabase-js installed.SUPABASE_URL and SUPABASE_ANON_KEY (or SUPABASE_SERVICE_ROLE_KEY) configured.Access to Supabase Dashboard.Supabase CLI installed for local development.

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.

SkillInstallsUpdatedSafetyDifficulty
supabase-common-errors (this skill)44moReviewIntermediate
data-safety-auditor311moNo flagsAdvanced
supabase-postgres-best-practices410moNo flagsIntermediate
supabase-policy-guardrails34moReviewAdvanced

Try saying

Example prompts that trigger this skill in your AI assistant.

More by jeremylongshore

View all by jeremylongshore →

analyzing-logs

jeremylongshore

Analyze application logs to detect performance issues, identify error patterns, and improve stability by extracting key insights.

14123

ollama-setup

jeremylongshore

Configure auto-configure Ollama when user needs local LLM deployment, free AI alternatives, or wants to eliminate hosted API costs. Trigger phrases: "install ollama", "local AI", "free LLM", "self-hosted AI", "replace OpenAI", "no API costs". Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.

1167

backtesting-trading-strategies

jeremylongshore

Backtest crypto and traditional trading strategies against historical data. Calculates performance metrics (Sharpe, Sortino, max drawdown), generates equity curves, and optimizes strategy parameters. Use when user wants to test a trading strategy, validate signals, or compare approaches. Trigger with phrases like "backtest strategy", "test trading strategy", "historical performance", "simulate trades", "optimize parameters", or "validate signals".

1071

generating-database-seed-data

jeremylongshore

Process this skill enables AI assistant to generate realistic test data and database seed scripts for development and testing environments. it uses faker libraries to create realistic data, maintains relational integrity, and allows configurable data volumes. u... Use when working with databases or data models. Trigger with phrases like 'database', 'query', or 'schema'.

1033

cursor-codebase-indexing

jeremylongshore

Execute set up and optimize Cursor codebase indexing. Triggers on "cursor index setup", "codebase indexing", "index codebase", "cursor semantic search". Use when working with cursor codebase indexing functionality. Trigger with phrases like "cursor codebase indexing", "cursor indexing", "cursor".

885

testing-mobile-apps

jeremylongshore

Execute mobile app testing on iOS and Android devices/simulators. Use when performing specialized testing. Trigger with phrases like "test mobile app", "run iOS tests", or "validate Android functionality".

810

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.

38

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.

439

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

331

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

13

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

12

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.

11

Search skills

Search the agent skills registry