mirror of
https://github.com/supabase/supabase.git
synced 2026-10-07 02:15:05 +03:00
Jordi Enric
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
102 lines
3.5 KiB
TypeScript
102 lines
3.5 KiB
TypeScript
import { render, screen } from '@testing-library/react'
|
|
import { ConnectionTimeoutError } from 'types/api-errors'
|
|
import { ResponseError } from 'types/base'
|
|
import { beforeEach, describe, expect, it, vi } from 'vitest'
|
|
|
|
import { ErrorMatcher } from './ErrorMatcher'
|
|
|
|
vi.mock('lib/telemetry/track', () => ({ useTrack: () => vi.fn() }))
|
|
vi.mock('state/ai-assistant-state', () => ({
|
|
useAiAssistantStateSnapshot: () => ({ newChat: vi.fn() }),
|
|
}))
|
|
vi.mock('state/sidebar-manager-state', () => ({
|
|
useSidebarManagerSnapshot: () => ({ openSidebar: vi.fn() }),
|
|
}))
|
|
vi.mock('components/layouts/ProjectLayout/LayoutSidebar/LayoutSidebarProvider', () => ({
|
|
SIDEBAR_KEYS: { AI_ASSISTANT: 'ai-assistant' },
|
|
}))
|
|
vi.mock('./RestartProjectDialog', () => ({
|
|
RestartProjectDialog: () => null,
|
|
}))
|
|
|
|
describe('ErrorMatcher', () => {
|
|
beforeEach(() => vi.clearAllMocks())
|
|
|
|
it('renders the provided title and error message', () => {
|
|
render(
|
|
<ErrorMatcher
|
|
title="Failed to load tables"
|
|
error="ERROR: FAILED TO RUN SQL QUERY: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT."
|
|
supportFormParams={{}}
|
|
/>
|
|
)
|
|
expect(screen.getByText('Failed to load tables')).toBeInTheDocument()
|
|
expect(
|
|
screen.getByText(
|
|
'ERROR: FAILED TO RUN SQL QUERY: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT.'
|
|
)
|
|
).toBeInTheDocument()
|
|
})
|
|
|
|
it('renders troubleshooting steps for classified errors', () => {
|
|
const error = new ConnectionTimeoutError('CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT')
|
|
render(<ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{}} />)
|
|
expect(screen.getByText('Try restarting your project')).toBeInTheDocument()
|
|
expect(screen.getByText('Try our troubleshooting guide')).toBeInTheDocument()
|
|
expect(screen.getByText('Debug with AI')).toBeInTheDocument()
|
|
})
|
|
|
|
it('renders fallback for plain ResponseError (not a classified subclass)', () => {
|
|
render(
|
|
<ErrorMatcher
|
|
title="Failed to load tables"
|
|
error={new ResponseError('CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT')}
|
|
supportFormParams={{}}
|
|
/>
|
|
)
|
|
expect(screen.getByText('Failed to load tables')).toBeInTheDocument()
|
|
expect(screen.queryByText('Try restarting your project')).not.toBeInTheDocument()
|
|
})
|
|
|
|
it('renders fallback with provided title for unmatched errors', () => {
|
|
render(
|
|
<ErrorMatcher title="Failed to load tables" error="UNKNOWN ERROR" supportFormParams={{}} />
|
|
)
|
|
expect(screen.getByText('Failed to load tables')).toBeInTheDocument()
|
|
expect(screen.getByText('UNKNOWN ERROR')).toBeInTheDocument()
|
|
})
|
|
|
|
it('accepts error as object with message property', () => {
|
|
render(
|
|
<ErrorMatcher
|
|
title="Failed to load tables"
|
|
error={{ message: 'UNKNOWN ERROR' }}
|
|
supportFormParams={{}}
|
|
/>
|
|
)
|
|
expect(screen.getByText('UNKNOWN ERROR')).toBeInTheDocument()
|
|
})
|
|
|
|
it('builds support link with projectRef param', () => {
|
|
render(
|
|
<ErrorMatcher
|
|
title="Failed to load tables"
|
|
error="UNKNOWN ERROR"
|
|
supportFormParams={{ projectRef: 'my-project' }}
|
|
/>
|
|
)
|
|
expect(screen.getByRole('link', { name: /contact support/i })).toHaveAttribute(
|
|
'href',
|
|
'/support/new?projectRef=my-project'
|
|
)
|
|
})
|
|
|
|
it('builds support link with no params when supportFormParams is omitted', () => {
|
|
render(<ErrorMatcher title="Failed to load tables" error="UNKNOWN ERROR" />)
|
|
expect(screen.getByRole('link', { name: /contact support/i })).toHaveAttribute(
|
|
'href',
|
|
'/support/new'
|
|
)
|
|
})
|
|
})
|