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

Which component

AlertError (default)

Renders a warning Admonition with the error message, generic "try refreshing / contact support" instructions, and a Contact support button pre-filled with projectRef, subject, and the error message.

if (isError) return <AlertError error={error} subject="Failed to retrieve invoices" />

• subject is the human-readable title, phrased Failed to <verb> <thing>. Pass projectRef when in a project context so the support form is pre-filled.
• error is the React Query error object (anything with message); 503 responses are reworded automatically.
• Use additionalActions for a retry or navigate button; hideContactSupport only when support genuinely can't help (e.g. a user-input error).
• Prefer the early-return form for the page/section's primary data; use inline {isError && <AlertError … />} for secondary panels that shouldn't block the rest of the page.

ErrorMatcher (classified errors)

Use when the data layer may have classified the error into a KnownErrorType with dedicated troubleshooting UI. It reads errorType from the error instance and renders the mapped Troubleshooting component, or fallback when there is no mapping. Today this is wired for the table editor sidebar; reach for it when adding troubleshooting for a new error type rather than as a general replacement for AlertError.

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