playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / supabase-common-errors

supabase-common-errors skill

/plugins/saas-packs/supabase-pack/skills/supabase-common-errors

This skill helps diagnose and fix common Supabase errors by guiding identification, matching, and applying proven resolutions.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill supabase-common-errors

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.2 KB
---
name: supabase-common-errors
description: |
  Execute diagnose and fix Supabase common errors and exceptions.
  Use when encountering Supabase errors, debugging failed requests,
  or troubleshooting integration issues.
  Trigger with phrases like "supabase error", "fix supabase",
  "supabase not working", "debug supabase".
allowed-tools: Read, Grep, Bash(curl:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Supabase Common Errors

## Prerequisites
- Supabase SDK installed
- API credentials configured
- Access to error logs

## Instructions

### Step 1: Identify the Error
Check error message and code in your logs or console.

### Step 2: Find Matching Error Below
Match your error to one of the documented cases.

### Step 3: Apply Solution
Follow the solution steps for your specific error.

## Output
- Identified error cause
- Applied fix
- Verified resolution

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Supabase Status Page](https://status.supabase.com)
- [Supabase Support](https://supabase.com/docs/support)
- [Supabase Error Codes](https://supabase.com/docs/errors)

Overview

This skill diagnoses and fixes common Supabase errors and exceptions encountered in client and server integrations. It guides you from identifying error codes in logs to applying targeted fixes and verifying resolution. The goal is to restore functionality quickly and reduce repetitive debugging steps.

How this skill works

The skill inspects Supabase error messages, HTTP status codes, SDK exceptions, and request logs to identify the root cause. It matches the observed error to known cases and recommends concrete remediation steps such as configuration fixes, permission updates, or query adjustments. After applying a fix, it suggests verification checks and follow-up actions to prevent recurrence.

When to use it

  • When API requests to Supabase return errors or unexpected statuses
  • When authentication or authorization operations fail (sign-in, JWT, RLS issues)
  • When real-time subscriptions or replication are not working
  • When database queries fail, time out, or return permission-denied errors
  • During CI/CD deploys that break Supabase integration

Best practices

  • Capture and include the full error message and HTTP status code when diagnosing
  • Confirm API keys, project URL, and client SDK versions before deeper debugging
  • Check Row-Level Security (RLS) policies and database roles for permission issues
  • Use logs and request traces to reproduce the failure locally or in a staging environment
  • Automate common fixes (retries, backoff, health checks) and add monitoring for key endpoints

Example use cases

  • Fixing a 401/403 due to expired or misconfigured API keys and regenerating service role keys
  • Resolving RLS permission-denied errors by updating policies or using correct JWT claims
  • Diagnosing real-time connection failures by checking WebSocket endpoints, CORS, and network rules
  • Troubleshooting database query timeouts by optimizing indexes, refactoring queries, or adjusting pool settings
  • Repairing CORS and origin issues that block browser-based requests to Supabase

FAQ

What information should I provide to get the fastest diagnosis?

Provide the exact error text, HTTP status code, SDK version, relevant request payload, and recent logs or stack traces.

Can this skill fix production incidents automatically?

It recommends fixes and verification steps. Automated remediation is possible if you wire the recommendations into scripts or CI/CD, but manual review is recommended for production changes.