supabase-advanced-troubleshooting
Apply Supabase advanced debugging techniques for hard-to-diagnose issues.Use when standard troubleshooting fails, investigating complex race conditions,or preparing evidence bundles for Supabase support escalation.Trigger with phrases like "supabase hard bug", "supabase mystery error","supabase impossible to debug", "difficult supabase issue", "supabase deep debug".
When & Why to Use This Skill
The Supabase Advanced Troubleshooting skill is a specialized diagnostic tool designed for developers and SREs to resolve high-complexity database and backend issues. It automates deep-dive diagnostics for Supabase environments, handling everything from intermittent race condition investigation to the generation of technical evidence bundles for support escalations using advanced tools like kubectl and tcpdump.
Use Cases
- Investigating Complex Race Conditions: Systematically isolate and identify the root cause of non-deterministic errors in Supabase environments that standard logs fail to capture.
- Automated Evidence Collection for Support: Streamline the escalation process by automatically gathering comprehensive diagnostic data, including network captures and cluster metrics, for Supabase support teams.
- Deep-Level Infrastructure Diagnostics: Use low-level tools like tcpdump and kubectl to isolate connectivity bottlenecks or performance regressions within the Supabase stack.
- Systematic Failure Isolation: Execute a step-by-step methodology to strip down complex failing cases into minimal reproductions for faster debugging.
| name | supabase-advanced-troubleshooting |
|---|---|
| description | | |
| allowed-tools | Read, Grep, Bash(kubectl:*), Bash(curl:*), Bash(tcpdump:*) |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
Supabase Advanced Troubleshooting
Prerequisites
- Access to production logs and metrics
- kubectl access to clusters
- Network capture tools available
- Understanding of distributed tracing
Instructions
Step 1: Collect Evidence Bundle
Run the comprehensive debug script to gather all relevant data.
Step 2: Systematic Isolation
Test each layer independently to identify the failure point.
Step 3: Create Minimal Reproduction
Strip down to the simplest failing case.
Step 4: Escalate with Evidence
Use the support template with all collected evidence.
Output
- Comprehensive debug bundle collected
- Failure layer identified
- Minimal reproduction created
- Support escalation submitted
Error Handling
See {baseDir}/references/errors.md for comprehensive error handling.
Examples
See {baseDir}/references/examples.md for detailed examples.