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.
Full docs and code examples: apps/studio/components/interfaces/ErrorHandling/README.md
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
| 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 |
Pass the full error object from React Query — not error.message:
{
isError && (
<ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{ projectRef }} />
)
}
error.message to ErrorMatcher — pass the full error object so the class is preserved.error-mappings.tsx — they belong in data/error-patterns.ts.Object.assign to stamp errorType — throw a proper subclass instead.supportFormParams={{ projectRef }}.<ErrorMatcher> caller.onDebugWithAI, onRestartProject) to troubleshooting components — use hooks inside them instead.