---

name: studio-error-handling description: Error display and troubleshooting pattern for Supabase Studio. Use when showing a failed API request or query error in the UI (AlertError, toast, inline message), adding 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.

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