studio-error-handling

✓ Official★ 105,700

Error display and troubleshooting pattern for Supabase Studio. Use when

🔥🔥✓ VerifiedFreeQuick setup

🔒 Repo-maintenance skill. It exists to help maintain supabase/supabase itself — it's only useful if you contribute code to that project.

Error display and troubleshooting pattern for Supabase Studio. Use when

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

name: studio-error-handling description: Error display and troubleshooting pattern for Supabase Studio. Use when rendering API errors in the UI, adding inline troubleshooting steps for a new error type, or wiring up the AI assistant debug button from an error state.

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

Copy & paste — that's it

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

What NOT to do

Do not pass error.message to ErrorMatcher — pass the full error object so the class is preserved.
Do not put regex patterns in error-mappings.tsx — they belong in data/error-patterns.ts.
Do not use Object.assign to stamp errorType — 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.

Copy & paste — that's it

npx skills add https://github.com/supabase/supabase --skill studio-error-handling

Run this in your project — your agent picks the skill up automatically.

Usage

Pass the full error object from React Query — not error.message:

Copy & paste — that's it

{
  isError && (
    <ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{ projectRef }} />
  )
}