mirror of
https://github.com/supabase/supabase.git
synced 2026-05-09 08:18:16 +08:00
ec26943390
When the dashboard hits a DB connection timeout, users currently see a
raw error message with no
path forward. This PR adds an inline troubleshooting system that detects
known error types and
surfaces contextual next steps — restart the DB, read the docs, or debug
with AI.
## Changes
- New ErrorDisplay component (packages/ui-patterns) — styled error card
with a title, monospace error
block, optional troubleshooting slot, and a "Contact support" link that
always renders. Accepts
typed supportFormParams to pre-fill the support form.
- Error classification in handleError (data/fetchers.ts) — on every API
error, the message is tested
against ERROR_PATTERNS. If matched, handleError throws a typed subclass
(ConnectionTimeoutError
extends ResponseError) instead of a plain ResponseError. Stack traces
now show the exact error
class. All existing instanceof ResponseError checks continue to work.
- ErrorMatcher component — reads errorType from the thrown class
instance, does an O(1) lookup into
ERROR_MAPPINGS, and renders the matching troubleshooting accordion as
children of ErrorDisplay.
Falls back to plain ErrorDisplay for unclassified errors.
- Connection timeout mapping — first error type wired up, with three
troubleshooting steps: restart
the database, link to the docs, and "Debug with AI" (opens the AI
assistant sidebar with a
pre-filled prompt).
- Telemetry — three new typed events track when the troubleshooter is
shown, when accordion steps are
toggled, and which CTAs are clicked.
## Adding a new error type
1. Add a class to types/api-errors.ts
2. Add { pattern, ErrorClass } to data/error-patterns.ts
3. Create a troubleshooting component in errorMappings/
4. Add an entry to error-mappings.tsx
60 lines
3.3 KiB
Plaintext
60 lines
3.3 KiB
Plaintext
---
|
|
title: Error Display
|
|
description: A card component for surfacing API errors with optional troubleshooting steps and a support link.
|
|
fragment: true
|
|
---
|
|
|
|
ErrorDisplay renders a styled error card with a warning header, a monospace error message block, an optional children slot for inline troubleshooting content, and a "Contact support" footer link that is always shown.
|
|
|
|
<ComponentPreview name="error-display-demo" peekCode wide />
|
|
|
|
Use ErrorDisplay as the base for any inline error state in the dashboard. For errors with known patterns, wire up [`ErrorMatcher`](https://github.com/supabase/supabase/tree/master/apps/studio/components/interfaces/ErrorHandling) on top to automatically inject matching troubleshooting steps.
|
|
|
|
## Usage
|
|
|
|
```tsx
|
|
import { ErrorDisplay } from 'ui-patterns/ErrorDisplay'
|
|
```
|
|
|
|
```tsx
|
|
<ErrorDisplay
|
|
title="Failed to load tables"
|
|
errorMessage="ERROR: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT."
|
|
supportFormParams={{ projectRef: 'my-project' }}
|
|
/>
|
|
```
|
|
|
|
## Examples
|
|
|
|
### With troubleshooting steps
|
|
|
|
Pass any content as `children` — typically a `TroubleshootingAccordion` — to render inline troubleshooting between the error message and the support footer.
|
|
|
|
<ComponentPreview name="error-display-with-children" peekCode wide />
|
|
|
|
## Props
|
|
|
|
| Prop | Type | Default | Description |
|
|
| ------------------- | -------------------- | ------------------- | --------------------------------------------------------------------- |
|
|
| `title` | `string` | — | Displayed in the card header next to the warning icon. |
|
|
| `errorMessage` | `string` | — | Raw error string rendered in a monospace code block. |
|
|
| `supportFormParams` | `SupportFormParams?` | `undefined` | Typed params for the support form URL. The component builds the URL. |
|
|
| `supportLabel` | `string?` | `"Contact support"` | Override the support link label. |
|
|
| `children` | `ReactNode` | `undefined` | Slot for troubleshooting content rendered between message and footer. |
|
|
| `icon` | `ReactNode` | Warning triangle | Override the header icon. |
|
|
| `onRender` | `() => void?` | — | Fired once on mount — use for telemetry. |
|
|
| `onSupportClick` | `() => void?` | — | Fired when the support link is clicked — use for telemetry. |
|
|
| `className` | `string?` | — | Extra classes on the root `Card`. |
|
|
|
|
### SupportFormParams
|
|
|
|
| Field | Type | Description |
|
|
| ------------ | --------- | ----------------------------- |
|
|
| `projectRef` | `string?` | Project reference slug |
|
|
| `orgSlug` | `string?` | Organisation slug |
|
|
| `category` | `string?` | Pre-selected support category |
|
|
| `subject` | `string?` | Pre-filled subject line |
|
|
| `message` | `string?` | Pre-filled message body |
|
|
| `error` | `string?` | Raw error string for context |
|
|
| `sid` | `string?` | Sentry event ID |
|