Studio Error Handling
OfficialFreeEfficiently manage and display API errors in Supabase Studio.
Free · Opens the source repo
What Studio Error Handling does
The Studio Error Handling skill provides a structured approach to error management within Supabase Studio applications. It utilizes a classification system that operates in the data layer, where errors are analyzed and categorized based on predefined patterns. When an API request fails, the handleError function in data/fetchers.ts identifies the error type and throws the appropriate subclass, such as ConnectionTimeoutError. This ensures that the error is not only caught but also categorized correctly for user-friendly display.
The main component responsible for rendering these errors is ErrorMatcher, which performs an efficient lookup of the error type to display relevant troubleshooting information. This avoids the overhead of regex matching, allowing for quick and responsive error handling. By passing the full error object to ErrorMatcher, developers can leverage the complete error context, ensuring that users receive accurate and helpful feedback when something goes wrong.
This skill is particularly useful for developers working with Supabase who need to enhance user experience by providing clear and actionable error messages. It streamlines the process of adding troubleshooting steps for new error types and integrates seamlessly with the AI assistant debug button, making it a valuable addition to any Supabase project.
By adhering to the guidelines outlined in the skill, developers can ensure that error handling is consistent and effective, improving both the reliability of the application and the overall user experience.
When to use it
Use this skill when implementing error handling for API requests in Supabase Studio to ensure users receive clear and actionable feedback.
When not to use it
This skill is not suitable for applications outside of the Supabase ecosystem or for general error handling unrelated to API requests.
What you can build with it
Displaying Connection Errors
When a connection timeout occurs, use the Studio Error Handling skill to display a user-friendly error message with troubleshooting steps.
Integrating AI Debugging
Utilize the AI assistant debug button in conjunction with error handling to provide users with immediate support options during failures.
Adding New Error Types
Easily extend the error handling system by adding new error types and corresponding troubleshooting components as needed.
How to install Studio Error Handling
View source1. Install with the skills CLI
npx skills add supabase/supabase/studio-error-handling --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by supabaseStudio Error Handling Pattern
Full docs and code examples: apps/studio/components/interfaces/ErrorHandling/README.md
How it works
Classification happens in the data layer: handleError in data/fetchers.ts tests the error message against ERROR_PATTERNS and throws the matching error subclass (e.g. ConnectionTimeoutError extends ResponseError). The component (ErrorMatcher) reads errorType from the instance and does an O(1) lookup — it never does regex matching.
handleError() → throws ConnectionTimeoutError → React Query catches → ErrorMatcher reads errorType → renders troubleshooting
Key files
| File | Purpose |
|---|---|
data/error-patterns.ts | Array of { pattern, ErrorClass } — the regex lives here |
types/api-errors.ts | Error classes, KnownErrorType union, ClassifiedError type |
ErrorMatcher.tsx | Component — reads errorType, looks up mapping, renders |
error-mappings.tsx | Record<KnownErrorType, { id, Troubleshooting: ComponentType }> |
errorMappings/ConnectionTimeout.tsx | Reference troubleshooting component |
TroubleshootingSections.tsx | Reusable accordion section components |
TroubleshootingAccordion.tsx | Accordion wrapper with telemetry |
Usage
Pass the full error object from React Query — not error.message:
{
isError && (
<ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{ projectRef }} />
)
}
What NOT to do
- Do not pass
error.messagetoErrorMatcher— pass the fullerrorobject so the class is preserved. - Do not put regex patterns in
error-mappings.tsx— they belong indata/error-patterns.ts. - Do not use
Object.assignto stamperrorType— throw a proper subclass instead. - Do not pass a raw URL string for support — use
supportFormParams={{ projectRef }}. - Do not put the page title inside the error mapping — it belongs on the
<ErrorMatcher>caller. - Do not add callback props (
onDebugWithAI,onRestartProject) to troubleshooting components — use hooks inside them instead.
Frequently asked questions about Studio Error Handling
Similar skills
Agent Host Debug Logs
Analyze Agent Host debug logs for deeper insights.
Code OSS Dev - Launch + Debug
Launch and debug Code OSS with isolated profiles.
Phoenix CLI
Debug LLM applications with structured analysis tools.
Power Automate Debugging
Diagnose and fix Power Automate flow errors effectively.
Arize Trace
Inspect and export traces for LLM applications.
Runtime Behavior Probe
Investigate real runtime behavior with precision.