Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat: improve db overload debugging UX (#43564)

Jordi Enricec26943390c8
diff --git a/.claude/skills/studio-error-handling/SKILL.md b/.claude/skills/studio-error-handling/SKILL.md
new file mode 100644
index 00000000000..de0ff4cbab9
--- /dev/null
+++ b/.claude/skills/studio-error-handling/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: studio-error-handling
+description: 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.
+---
+
+# 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`:
+
+```tsx
+{
+ 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.
diff --git a/apps/design-system/config/docs.ts b/apps/design-system/config/docs.ts
index ab73703af78..cc1b8f213f7 100644
--- a/apps/design-system/config/docs.ts
+++ b/apps/design-system/config/docs.ts
@@ -167,6 +167,11 @@ export const docsConfig: DocsConfig = {
href: '/docs/fragments/data-input',
items: [],
},
+ {
+ title: 'Error Display',
+ href: '/docs/fragments/error-display',
+ items: [],
+ },
{
title: 'Form Item Layout',
href: '/docs/fragments/form-item-layout',
diff --git a/apps/design-system/content/docs/fragments/error-display.mdx b/apps/design-system/content/docs/fragments/error-display.mdx
new file mode 100644
index 00000000000..4b897b21e4e
--- /dev/null
+++ b/apps/design-system/content/docs/fragments/error-display.mdx
@@ -0,0 +1,59 @@
+---
+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 |
diff --git a/apps/design-system/registry/default/example/error-display-demo.tsx b/apps/design-system/registry/default/example/error-display-demo.tsx
new file mode 100644
index 00000000000..e994c90bd4e
--- /dev/null
+++ b/apps/design-system/registry/default/example/error-display-demo.tsx
@@ -0,0 +1,11 @@
+import { ErrorDisplay } from 'ui-patterns/ErrorDisplay'
+
+export default function ErrorDisplayDemo() {
+ return (
+ <ErrorDisplay
+ title="Failed to load tables"
+ errorMessage="ERROR: FAILED TO RUN SQL QUERY: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT."
+ supportFormParams={{ projectRef: 'my-project' }}
+ />
+ )
+}
diff --git a/apps/design-system/registry/default/example/error-display-with-children.tsx b/apps/design-system/registry/default/example/error-display-with-children.tsx
new file mode 100644
index 00000000000..9c2f1cf46bc
--- /dev/null
+++ b/apps/design-system/registry/default/example/error-display-with-children.tsx
@@ -0,0 +1,16 @@
+import { ErrorDisplay } from 'ui-patterns/ErrorDisplay'
+
+export default function ErrorDisplayWithChildren() {
+ return (
+ <ErrorDisplay
+ title="Failed to load tables"
+ errorMessage="ERROR: FAILED TO RUN SQL QUERY: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT."
+ supportFormParams={{ projectRef: 'my-project' }}
+ >
+ <div className="px-4 py-3 text-sm text-foreground-light border-b border-default">
+ Troubleshooting steps would appear here — e.g. a{' '}
+ <code className="font-mono text-xs">TroubleshootingAccordion</code>.
+ </div>
+ </ErrorDisplay>
+ )
+}
diff --git a/apps/design-system/registry/examples.ts b/apps/design-system/registry/examples.ts
index 821c5530446..34a31c697b7 100644
--- a/apps/design-system/registry/examples.ts
+++ b/apps/design-system/registry/examples.ts
@@ -1462,6 +1462,18 @@ export const examples: Registry = [
type: 'docs:example',
files: ['example/expanding-textarea-demo.tsx'],
},
+ {
+ name: 'error-display-demo',
+ type: 'components:example',
+ registryDependencies: ['error-display'],
+ files: ['example/error-display-demo.tsx'],
+ },
+ {
+ name: 'error-display-with-children',
+ type: 'components:example',
+ registryDependencies: ['error-display'],
+ files: ['example/error-display-with-children.tsx'],
+ },
{
name: 'logs-bar-chart',
type: 'components:example',
diff --git a/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.test.tsx b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.test.tsx
new file mode 100644
index 00000000000..38266a28e8d
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.test.tsx
@@ -0,0 +1,101 @@
+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'
+ )
+ })
+})
diff --git a/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.tsx b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.tsx
new file mode 100644
index 00000000000..37381adefa5
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.tsx
@@ -0,0 +1,51 @@
+'use client'
+
+import { useTrack } from 'lib/telemetry/track'
+import { ErrorDisplay, SupportFormParams } from 'ui-patterns/ErrorDisplay'
+
+import { getMappingForError } from './ErrorMatcher.utils'
+
+interface ErrorMatcherProps {
+ title: string
+ error: string | { message: string }
+ supportFormParams?: SupportFormParams
+ className?: string
+}
+
+export function ErrorMatcher({ title, error, supportFormParams, className }: ErrorMatcherProps) {
+ const track = useTrack()
+
+ const message = typeof error === 'string' ? error : error.message
+ const mapping = getMappingForError(error)
+ const Troubleshooting = mapping?.Troubleshooting
+
+ return (
+ <ErrorDisplay
+ title={title}
+ errorMessage={message}
+ supportFormParams={supportFormParams}
+ className={className}
+ onRender={() => {
+ track('dashboard_error_created', {
+ source: 'error_display',
+ errorType: mapping?.id,
+ hasTroubleshooting: !!mapping,
+ })
+ if (mapping) {
+ track('inline_error_troubleshooter_exposed', { errorType: mapping.id })
+ }
+ }}
+ onSupportClick={
+ mapping
+ ? () =>
+ track('inline_error_troubleshooter_action_clicked', {
+ errorType: mapping.id,
+ ctaType: 'contact_support',
+ })
+ : undefined
+ }
+ >
+ {Troubleshooting && <Troubleshooting />}
+ </ErrorDisplay>
+ )
+}
diff --git a/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.utils.test.ts b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.utils.test.ts
new file mode 100644
index 00000000000..34d3a7cbe90
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.utils.test.ts
@@ -0,0 +1,34 @@
+import { ConnectionTimeoutError, UnknownAPIResponseError } from 'types/api-errors'
+import { describe, expect, it } from 'vitest'
+
+import { getMappingForError } from './ErrorMatcher.utils'
+
+describe('getMappingForError', () => {
+ it('returns the mapping for a classified error with a known errorType', () => {
+ const error = new ConnectionTimeoutError('connection terminated due to connection timeout')
+ const mapping = getMappingForError(error)
+ expect(mapping).not.toBeNull()
+ expect(mapping?.id).toBe('connection-timeout')
+ })
+
+ it('returns null for UnknownAPIResponseError (no troubleshooting guide)', () => {
+ const error = new UnknownAPIResponseError('something went wrong')
+ expect(getMappingForError(error)).toBeNull()
+ })
+
+ it('returns null for a plain string', () => {
+ expect(getMappingForError('some error message')).toBeNull()
+ })
+
+ it('returns null for null', () => {
+ expect(getMappingForError(null)).toBeNull()
+ })
+
+ it('returns null for an object with no errorType', () => {
+ expect(getMappingForError({ message: 'error' })).toBeNull()
+ })
+
+ it('returns null for an object with an unrecognised errorType', () => {
+ expect(getMappingForError({ errorType: 'not-a-real-type' })).toBeNull()
+ })
+})
diff --git a/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.utils.ts b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.utils.ts
new file mode 100644
index 00000000000..09f73218315
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.utils.ts
@@ -0,0 +1,12 @@
+import { ResponseError } from 'types/base'
+
+import { ERROR_MAPPINGS, type ErrorMapping } from './error-mappings'
+
+export function getMappingForError(error: unknown): ErrorMapping | null {
+ const isResponseError = error instanceof ResponseError
+ if (!isResponseError) return null
+ for (const [ErrorClass, mapping] of ERROR_MAPPINGS) {
+ if (error instanceof ErrorClass) return mapping
+ }
+ return null
+}
diff --git a/apps/studio/components/interfaces/ErrorHandling/README.md b/apps/studio/components/interfaces/ErrorHandling/README.md
new file mode 100644
index 00000000000..dda0f17e2ab
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/README.md
@@ -0,0 +1,130 @@
+# Error Handling
+
+`ErrorMatcher` displays a typed API error. If the error was classified by `handleError` (i.e. it is an instance of a known error class), it shows matching troubleshooting steps. Otherwise it shows a generic error card.
+
+Classification happens in the data layer — `handleError` in `data/fetchers.ts` matches the error message against patterns and throws the appropriate error subclass (e.g. `ConnectionTimeoutError`). The component never does regex matching itself.
+
+The `title` always comes from the caller — the same error type can appear on different pages with different titles.
+
+## Usage
+
+```tsx
+import { ErrorMatcher } from 'components/interfaces/ErrorHandling/ErrorMatcher'
+
+{
+ isError && (
+ <ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{ projectRef }} />
+ )
+}
+```
+
+Pass the full `error` object from React Query — not `error.message`. This lets `ErrorMatcher` check the error class and show the right troubleshooting steps.
+
+### Props
+
+| Prop | Type | Description |
+| ------------------- | ------------------------------- | ------------------------------------------------------------------ |
+| `title` | `string` | Displayed in the error card header. Set by the caller. |
+| `error` | `string \| { message: string }` | The error from React Query (pass the full object, not `.message`). |
+| `supportFormParams` | `Partial<SupportFormUrlKeys>` | Typed params for the support form URL (projectRef, category…). |
+| `className` | `string?` | Extra classes on the card. |
+
+`supportFormParams` is typed as `Partial<SupportFormUrlKeys>` — autocomplete shows all available fields (`projectRef`, `orgSlug`, `category`, `subject`, `message`, `error`, `sid`). The URL is built by `createSupportFormUrl()` from `SupportForm.utils.tsx`.
+
+## Adding a new error mapping
+
+**1. Add the error class to `types/api-errors.ts`**
+
+```ts
+export type KnownErrorType = 'connection-timeout' | 'your-error'
+
+export class YourError extends ResponseError {
+ readonly errorType = 'your-error' as const
+}
+
+export type ClassifiedError = ConnectionTimeoutError | FailedToRetrieveProjectsError | YourError
+```
+
+**2. Add a pattern entry to `data/error-patterns.ts`**
+
+```ts
+import { YourError } from 'types/api-errors'
+
+export const ERROR_PATTERNS: ErrorPattern[] = [
+ // existing...
+ {
+ pattern: /YOUR_ERROR_PATTERN/i,
+ ErrorClass: YourError,
+ },
+]
+```
+
+`handleError` picks this up automatically — any matching API error will be thrown as a `YourError` instance.
+
+**3. Create `errorMappings/YourError.tsx`**
+
+```tsx
+import { SIDEBAR_KEYS } from 'components/layouts/ProjectLayout/LayoutSidebar/LayoutSidebarProvider'
+import { useAiAssistantStateSnapshot } from 'state/ai-assistant-state'
+import { useSidebarManagerSnapshot } from 'state/sidebar-manager-state'
+
+import { TroubleshootingAccordion } from '../TroubleshootingAccordion'
+import {
+ FixWithAITroubleshootingSection,
+ TroubleshootingGuideSection,
+} from '../TroubleshootingSections'
+
+const ERROR_TYPE = 'your-error'
+const BUILD_PROMPT = () => `Describe the issue for the AI assistant.`
+
+export function YourErrorTroubleshooting() {
+ const { openSidebar } = useSidebarManagerSnapshot()
+ const aiSnap = useAiAssistantStateSnapshot()
+
+ return (
+ <TroubleshootingAccordion
+ errorType={ERROR_TYPE}
+ stepTitles={{ 1: 'Troubleshooting guide', 2: 'Debug with AI' }}
+ >
+ <TroubleshootingGuideSection
+ number={1}
+ errorType={ERROR_TYPE}
+ href="https://supabase.com/docs/guides/..."
+ />
+ <FixWithAITroubleshootingSection
+ number={2}
+ errorType={ERROR_TYPE}
+ buildPrompt={BUILD_PROMPT}
+ onDebugWithAI={(prompt) => {
+ openSidebar(SIDEBAR_KEYS.AI_ASSISTANT)
+ aiSnap.newChat({ initialMessage: prompt })
+ }}
+ />
+ </TroubleshootingAccordion>
+ )
+}
+```
+
+**4. Add it to `error-mappings.tsx`**
+
+```tsx
+import { YourErrorTroubleshooting } from './errorMappings/YourError'
+
+export const ERROR_MAPPINGS: Record<KnownErrorType, ErrorMapping> = {
+ // existing...
+ 'your-error': {
+ id: 'your-error',
+ Troubleshooting: YourErrorTroubleshooting,
+ },
+}
+```
+
+That's it. `ErrorMatcher` picks it up automatically.
+
+## Available section components
+
+| Component | Props |
+| --------------------------------------- | ------------------------------------------------------- |
+| `RestartDatabaseTroubleshootingSection` | `number`, `errorType`, `onRestartProject?` |
+| `TroubleshootingGuideSection` | `number`, `errorType`, `href`, `title?`, `description?` |
+| `FixWithAITroubleshootingSection` | `number`, `errorType`, `buildPrompt`, `onDebugWithAI?` |
diff --git a/apps/studio/components/interfaces/ErrorHandling/RestartProjectDialog.tsx b/apps/studio/components/interfaces/ErrorHandling/RestartProjectDialog.tsx
new file mode 100644
index 00000000000..4e015f323d2
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/RestartProjectDialog.tsx
@@ -0,0 +1,104 @@
+'use client'
+
+import { PermissionAction } from '@supabase/shared-types/out/constants'
+import { useSetProjectStatus } from 'data/projects/project-detail-query'
+import { useProjectRestartMutation } from 'data/projects/project-restart-mutation'
+import { useProjectRestartServicesMutation } from 'data/projects/project-restart-services-mutation'
+import { useAsyncCheckPermissions } from 'hooks/misc/useCheckPermissions'
+import { useSelectedProjectQuery } from 'hooks/misc/useSelectedProject'
+import { PROJECT_STATUS } from 'lib/constants'
+import { useRouter } from 'next/router'
+import { toast } from 'sonner'
+import { ConfirmationModal } from 'ui-patterns/Dialogs/ConfirmationModal'
+
+interface RestartProjectDialogProps {
+ visible: boolean
+ onClose: () => void
+ /** Restart type: 'project' for full restart, 'database' for fast database reboot */
+ restartType?: 'project' | 'database'
+}
+
+export function RestartProjectDialog({
+ visible,
+ onClose,
+ restartType = 'database',
+}: RestartProjectDialogProps) {
+ const router = useRouter()
+ const { data: project } = useSelectedProjectQuery()
+ const { setProjectStatus } = useSetProjectStatus()
+
+ const { can: canRestartProject } = useAsyncCheckPermissions(
+ PermissionAction.INFRA_EXECUTE,
+ 'reboot'
+ )
+
+ const { mutate: restartProject, isPending: isRestartingProject } = useProjectRestartMutation({
+ onSuccess: () => {
+ if (project?.ref) {
+ setProjectStatus({ ref: project.ref, status: PROJECT_STATUS.RESTARTING })
+ }
+ toast.success('Restarting project')
+ router.push(`/project/${project?.ref}`)
+ onClose()
+ },
+ onError: (error) => {
+ toast.error(`Unable to restart project: ${error.message}`)
+ },
+ })
+
+ const { mutate: restartProjectServices, isPending: isRestartingServices } =
+ useProjectRestartServicesMutation({
+ onSuccess: () => {
+ if (project?.ref) {
+ setProjectStatus({ ref: project.ref, status: PROJECT_STATUS.RESTARTING })
+ }
+ toast.success('Restarting database')
+ router.push(`/project/${project?.ref}`)
+ onClose()
+ },
+ onError: (error) => {
+ toast.error(`Unable to restart database: ${error.message}`)
+ },
+ })
+
+ const isLoading = isRestartingProject || isRestartingServices
+
+ const handleRestart = () => {
+ if (!project?.ref) return
+
+ if (!canRestartProject) {
+ return toast.error('You do not have the required permissions to restart this project')
+ }
+
+ if (restartType === 'project') {
+ restartProject({ ref: project.ref })
+ } else {
+ restartProjectServices({
+ ref: project.ref,
+ region: project.region,
+ services: ['postgresql'],
+ })
+ }
+ }
+
+ const title = restartType === 'project' ? 'Restart project' : 'Restart database'
+ const description =
+ restartType === 'project'
+ ? 'Are you sure you want to restart your project? There will be a few minutes of downtime.'
+ : 'Are you sure you want to restart your database? There will be a brief downtime.'
+
+ return (
+ <ConfirmationModal
+ visible={visible}
+ variant="warning"
+ title={title}
+ description={description}
+ confirmLabel="Restart"
+ confirmLabelLoading="Restarting"
+ loading={isLoading}
+ disabled={!canRestartProject}
+ onCancel={onClose}
+ onConfirm={handleRestart}
+ />
+ )
+}
diff --git a/apps/studio/components/interfaces/ErrorHandling/TroubleshootingAccordion.tsx b/apps/studio/components/interfaces/ErrorHandling/TroubleshootingAccordion.tsx
new file mode 100644
index 00000000000..c65f398cabf
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/TroubleshootingAccordion.tsx
@@ -0,0 +1,48 @@
+'use client'
+
+import { useTrack } from 'lib/telemetry/track'
+import { ReactNode } from 'react'
+import { Accordion_Shadcn_ as Accordion, cn } from 'ui'
+
+interface TroubleshootingAccordionProps {
+ children: ReactNode
+ /** Error mapping ID — used for telemetry */
+ errorType: string
+ /** Step titles keyed by step number — used for telemetry */
+ stepTitles?: Record<number, string>
+ /** Which step to expand by default (1-indexed), defaults to 1 */
+ defaultExpandedStep?: number
+ className?: string
+}
+
+export function TroubleshootingAccordion({
+ children,
+ errorType,
+ stepTitles,
+ defaultExpandedStep = 1,
+ className,
+}: TroubleshootingAccordionProps) {
+ const track = useTrack()
+ const defaultValue = defaultExpandedStep > 0 ? `step-${defaultExpandedStep}` : undefined
+
+ return (
+ <Accordion
+ type="single"
+ collapsible
+ defaultValue={defaultValue}
+ className={cn('w-full', className)}
+ onValueChange={(value) => {
+ const expanded = Boolean(value)
+ const step = expanded ? parseInt(value.replace('step-', ''), 10) : null
+ track('inline_error_troubleshooter_step_clicked', {
+ errorType,
+ step,
+ stepTitle: step !== null ? stepTitles?.[step] : undefined,
+ expanded,
+ })
+ }}
+ >
+ {children}
+ </Accordion>
+ )
+}
diff --git a/apps/studio/components/interfaces/ErrorHandling/TroubleshootingSections.tsx b/apps/studio/components/interfaces/ErrorHandling/TroubleshootingSections.tsx
new file mode 100644
index 00000000000..e1b7a4b46a1
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/TroubleshootingSections.tsx
@@ -0,0 +1,179 @@
+'use client'
+
+import { AiAssistantDropdown } from 'components/ui/AiAssistantDropdown'
+import { useTrack } from 'lib/telemetry/track'
+import { ExternalLink } from 'lucide-react'
+import { useState } from 'react'
+import {
+ AccordionContent_Shadcn_ as AccordionContent,
+ AccordionItem_Shadcn_ as AccordionItem,
+ AccordionTrigger_Shadcn_ as AccordionTrigger,
+ Button,
+} from 'ui'
+
+import { RestartProjectDialog } from './RestartProjectDialog'
+
+interface StepTriggerProps {
+ number: number
+ title: string
+}
+
+function StepTrigger({ number, title }: StepTriggerProps) {
+ return (
+ <AccordionTrigger className="py-3 hover:no-underline">
+ <div className="flex items-center gap-2.5">
+ <span className="flex-shrink-0 w-6 h-6 border border-button-hover text-foreground font-mono tabular-nums bg-button rounded-md text-xs font-medium flex items-center justify-center">
+ {number}
+ </span>
+ <span className="text-sm font-medium text-foreground text-left">{title}</span>
+ </div>
+ </AccordionTrigger>
+ )
+}
+
+interface RestartDatabaseTroubleshootingSectionProps {
+ number: number
+ errorType: string
+ /** Override the restart handler. If not provided, opens the restart dialog internally. */
+ onRestartProject?: () => void
+}
+
+export function RestartDatabaseTroubleshootingSection({
+ number,
+ errorType,
+ onRestartProject,
+}: RestartDatabaseTroubleshootingSectionProps) {
+ const track = useTrack()
+ const [showDialog, setShowDialog] = useState(false)
+
+ const handleClick = () => {
+ track('inline_error_troubleshooter_action_clicked', {
+ errorType,
+ ctaType: 'restart_db',
+ })
+ if (onRestartProject) {
+ onRestartProject()
+ } else {
+ setShowDialog(true)
+ }
+ }
+
+ return (
+ <>
+ <AccordionItem
+ value={`step-${number}`}
+ className="border-b border-default last:border-b-0 px-3 py-2"
+ >
+ <StepTrigger number={number} title="Try restarting your project" />
+ <AccordionContent className="pt-1">
+ <div className="px-2">
+ <p className="text-sm text-foreground-light mb-3">
+ Restarting your project can help resolve timeout errors or stale connections.
+ </p>
+ <Button type="default" size="tiny" onClick={handleClick}>
+ Restart project
+ </Button>
+ </div>
+ </AccordionContent>
+ </AccordionItem>
+
+ <RestartProjectDialog
+ visible={showDialog}
+ onClose={() => setShowDialog(false)}
+ restartType="database"
+ />
+ </>
+ )
+}
+
+interface TroubleshootingGuideSectionProps {
+ number: number
+ errorType: string
+ href: string
+ title?: string
+ description?: string
+}
+
+export function TroubleshootingGuideSection({
+ number,
+ errorType,
+ href,
+ title = 'Try our troubleshooting guide',
+ description,
+}: TroubleshootingGuideSectionProps) {
+ const track = useTrack()
+
+ return (
+ <AccordionItem
+ value={`step-${number}`}
+ className="border-b border-default last:border-b-0 px-3 py-2"
+ >
+ <StepTrigger number={number} title={title} />
+ <AccordionContent className="pt-1">
+ <div className="px-2">
+ {description && <p className="text-sm text-foreground-light mb-3">{description}</p>}
+ <Button
+ asChild
+ type="default"
+ size="tiny"
+ onClick={() =>
+ track('inline_error_troubleshooter_action_clicked', {
+ errorType,
+ ctaType: 'troubleshooting_guide',
+ })
+ }
+ iconRight={<ExternalLink />}
+ >
+ <a href={href} target="_blank" rel="noopener noreferrer">
+ View troubleshooting guide
+ </a>
+ </Button>
+ </div>
+ </AccordionContent>
+ </AccordionItem>
+ )
+}
+
+interface FixWithAITroubleshootingSectionProps {
+ number: number
+ errorType: string
+ description?: string
+ onDebugWithAI?: (prompt: string) => void
+ buildPrompt: () => string
+}
+
+export function FixWithAITroubleshootingSection({
+ number,
+ errorType,
+ description = 'Let our AI assistant help diagnose and suggest solutions.',
+ onDebugWithAI,
+ buildPrompt,
+}: FixWithAITroubleshootingSectionProps) {
+ const track = useTrack()
+
+ return (
+ <AccordionItem
+ value={`step-${number}`}
+ className="border-b border-default last:border-b-0 px-3 py-2"
+ >
+ <StepTrigger number={number} title="Debug with AI" />
+ <AccordionContent className="pt-1">
+ <div className="px-2">
+ <p className="text-sm text-foreground-light mb-3">{description}</p>
+ <AiAssistantDropdown
+ label="Debug with AI"
+ buildPrompt={buildPrompt}
+ onOpenAssistant={() => {
+ track('inline_error_troubleshooter_action_clicked', {
+ errorType,
+ ctaType: 'ask_ai',
+ })
+ onDebugWithAI?.(buildPrompt())
+ }}
+ size="tiny"
+ />
+ </div>
+ </AccordionContent>
+ </AccordionItem>
+ )
+}
diff --git a/apps/studio/components/interfaces/ErrorHandling/error-mappings.tsx b/apps/studio/components/interfaces/ErrorHandling/error-mappings.tsx
new file mode 100644
index 00000000000..c4095cae060
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/error-mappings.tsx
@@ -0,0 +1,19 @@
+import { ComponentType } from 'react'
+import { ConnectionTimeoutError } from 'types/api-errors'
+import type { ClassifiedError, KnownErrorType } from 'types/api-errors'
+
+import { ConnectionTimeoutTroubleshooting } from './errorMappings/ConnectionTimeout'
+
+export interface ErrorMapping {
+ id: KnownErrorType
+ Troubleshooting: ComponentType
+}
+
+type ErrorConstructor = new (...args: any[]) => ClassifiedError
+
+export const ERROR_MAPPINGS = new Map<ErrorConstructor, ErrorMapping>([
+ [
+ ConnectionTimeoutError,
+ { id: 'connection-timeout', Troubleshooting: ConnectionTimeoutTroubleshooting },
+ ],
+])
diff --git a/apps/studio/components/interfaces/ErrorHandling/errorMappings/ConnectionTimeout.tsx b/apps/studio/components/interfaces/ErrorHandling/errorMappings/ConnectionTimeout.tsx
new file mode 100644
index 00000000000..db01ae411df
--- /dev/null
+++ b/apps/studio/components/interfaces/ErrorHandling/errorMappings/ConnectionTimeout.tsx
@@ -0,0 +1,48 @@
+import { SIDEBAR_KEYS } from 'components/layouts/ProjectLayout/LayoutSidebar/LayoutSidebarProvider'
+import { useAiAssistantStateSnapshot } from 'state/ai-assistant-state'
+import { useSidebarManagerSnapshot } from 'state/sidebar-manager-state'
+
+import { TroubleshootingAccordion } from '../TroubleshootingAccordion'
+import {
+ FixWithAITroubleshootingSection,
+ RestartDatabaseTroubleshootingSection,
+ TroubleshootingGuideSection,
+} from '../TroubleshootingSections'
+
+const ERROR_TYPE = 'connection-timeout'
+
+const BUILD_PROMPT = () =>
+ `The user is encountering connection timeout errors. The error message is: "CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT". What are the most likely causes of this issue and how can the user resolve it?`
+
+export function ConnectionTimeoutTroubleshooting() {
+ const { openSidebar } = useSidebarManagerSnapshot()
+ const aiSnap = useAiAssistantStateSnapshot()
+
+ return (
+ <TroubleshootingAccordion
+ errorType={ERROR_TYPE}
+ stepTitles={{
+ 1: 'Try restarting your project',
+ 2: 'Try our troubleshooting guide',
+ 3: 'Debug with AI',
+ }}
+ >
+ <RestartDatabaseTroubleshootingSection number={1} errorType={ERROR_TYPE} />
+ <TroubleshootingGuideSection
+ number={2}
+ errorType={ERROR_TYPE}
+ href="https://supabase.com/docs/guides/troubleshooting/failed-to-run-sql-query-connection-terminated-due-to-connection-timeout"
+ description="Follow step-by-step instructions for diagnosing connection timeout issues."
+ />
+ <FixWithAITroubleshootingSection
+ number={3}
+ errorType={ERROR_TYPE}
+ onDebugWithAI={(prompt) => {
+ openSidebar(SIDEBAR_KEYS.AI_ASSISTANT)
+ aiSnap.newChat({ initialMessage: prompt })
+ }}
+ buildPrompt={BUILD_PROMPT}
+ />
+ </TroubleshootingAccordion>
+ )
+}
diff --git a/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx b/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx
index 96b9c286896..2990e303d92 100644
--- a/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx
+++ b/apps/studio/components/interfaces/Home/ProjectList/ProjectList.tsx
@@ -26,6 +26,8 @@ import {
TableRow,
} from 'ui'
+import { ErrorMatcher } from '../../ErrorHandling/ErrorMatcher'
+import { TroubleshootingAccordion } from '../../ErrorHandling/TroubleshootingAccordion'
import { LoadingCardView, LoadingTableView, NoProjectsState } from './EmptyStates'
import { LoadMoreRows } from './LoadMoreRow'
import { ProjectCard } from './ProjectCard'
diff --git a/apps/studio/components/interfaces/Support/SupportForm.utils.test.ts b/apps/studio/components/interfaces/Support/SupportForm.utils.test.ts
new file mode 100644
index 00000000000..4c2a584d430
--- /dev/null
+++ b/apps/studio/components/interfaces/Support/SupportForm.utils.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+
+import { createSupportFormUrl } from './SupportForm.utils'
+
+describe('createSupportFormUrl', () => {
+ it('returns base URL with no params', () => {
+ expect(createSupportFormUrl({})).toBe('/support/new')
+ })
+
+ it('does not append a bare ? when params are empty', () => {
+ expect(createSupportFormUrl({})).not.toContain('?')
+ })
+
+ it('includes provided params in the query string', () => {
+ const url = createSupportFormUrl({ projectRef: 'my-project' })
+ expect(url).toContain('projectRef=my-project')
+ })
+
+ it('includes multiple params', () => {
+ const url = createSupportFormUrl({ projectRef: 'my-project', subject: 'help' })
+ expect(url).toContain('projectRef=my-project')
+ expect(url).toContain('subject=help')
+ })
+})
diff --git a/apps/studio/components/interfaces/Support/SupportForm.utils.tsx b/apps/studio/components/interfaces/Support/SupportForm.utils.tsx
index 7f447168120..42aeb037a1b 100644
--- a/apps/studio/components/interfaces/Support/SupportForm.utils.tsx
+++ b/apps/studio/components/interfaces/Support/SupportForm.utils.tsx
@@ -143,7 +143,8 @@ const serializeSupportFormInitialParams = createSerializer(supportFormUrlState)
export function createSupportFormUrl(initialParams: Partial<SupportFormUrlKeys>) {
const serializedParams = serializeSupportFormInitialParams(initialParams)
- return `/support/new${serializedParams ?? ''}`
+ const query = serializedParams && serializedParams !== '?' ? serializedParams : ''
+ return `/support/new${query}`
}
/**
diff --git a/apps/studio/components/layouts/TableEditorLayout/TableEditorMenu.tsx b/apps/studio/components/layouts/TableEditorLayout/TableEditorMenu.tsx
index 9f63368ff44..9bc3596dc86 100644
--- a/apps/studio/components/layouts/TableEditorLayout/TableEditorMenu.tsx
+++ b/apps/studio/components/layouts/TableEditorLayout/TableEditorMenu.tsx
@@ -1,7 +1,4 @@
import { PermissionAction } from '@supabase/shared-types/out/constants'
-import { Filter, Plus } from 'lucide-react'
-import { useCallback, useEffect, useMemo, useState } from 'react'
-
import { keepPreviousData } from '@tanstack/react-query'
import { useParams } from 'common'
import { useBreakpoint } from 'common/hooks/useBreakpoint'
@@ -9,8 +6,8 @@ import { ExportDialog } from 'components/grid/components/header/ExportDialog'
import { parseSupaTable } from 'components/grid/SupabaseGrid.utils'
import { SupaTable } from 'components/grid/types'
import { ProtectedSchemaWarning } from 'components/interfaces/Database/ProtectedSchemaWarning'
+import { ErrorMatcher } from 'components/interfaces/ErrorHandling/ErrorMatcher'
import EditorMenuListSkeleton from 'components/layouts/TableEditorLayout/EditorMenuListSkeleton'
-import AlertError from 'components/ui/AlertError'
import { ButtonTooltip } from 'components/ui/ButtonTooltip'
import { InfiniteListDefault, LoaderForIconMenuItems } from 'components/ui/InfiniteList'
import SchemaSelector from 'components/ui/SchemaSelector'
@@ -23,22 +20,25 @@ import { useLocalStorage } from 'hooks/misc/useLocalStorage'
import { useQuerySchemaState } from 'hooks/misc/useSchemaQueryState'
import { useSelectedProjectQuery } from 'hooks/misc/useSelectedProject'
import { useIsProtectedSchema } from 'hooks/useProtectedSchemas'
+import { Filter, Plus } from 'lucide-react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
import { useTableEditorStateSnapshot } from 'state/table-editor'
import {
Button,
Checkbox_Shadcn_,
Label_Shadcn_,
+ Popover_Shadcn_,
PopoverContent_Shadcn_,
PopoverTrigger_Shadcn_,
- Popover_Shadcn_,
} from 'ui'
import {
InnerSideBarEmptyPanel,
+ InnerSideBarFilters,
InnerSideBarFilterSearchInput,
InnerSideBarFilterSortDropdown,
InnerSideBarFilterSortDropdownItem,
- InnerSideBarFilters,
} from 'ui-patterns/InnerSideMenu'
+
import { useTableEditorTabsCleanUp } from '../Tabs/Tabs.utils'
import { EntityListItem } from './EntityListItem'
import { TableMenuEmptyState } from './TableMenuEmptyState'
@@ -277,9 +277,12 @@ export const TableEditorMenu = () => {
{isLoading && <EditorMenuListSkeleton />}
{isError && (
- <div className="mx-4">
- <AlertError error={(error ?? null) as any} subject="Failed to retrieve tables" />
- </div>
+ <ErrorMatcher
+ title="Failed to load tables"
+ error={error ?? 'Failed to load tables'}
+ supportFormParams={{ projectRef: project?.ref }}
+ className="mx-4 mt-3"
+ />
)}
{isSuccess && (
diff --git a/apps/studio/data/error-patterns.test.ts b/apps/studio/data/error-patterns.test.ts
new file mode 100644
index 00000000000..6a551af70c7
--- /dev/null
+++ b/apps/studio/data/error-patterns.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+
+import { ERROR_PATTERNS } from './error-patterns'
+
+// Representative sample messages for each error class.
+// Keep this in sync when adding new patterns — the test will fail if you don't.
+const PATTERN_SAMPLES: Record<string, { matches: string[]; nonMatches: string[] }> = {
+ ConnectionTimeoutError: {
+ matches: [
+ 'CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT',
+ 'connection terminated due to connection timeout',
+ 'ERROR: FAILED TO RUN SQL QUERY: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT.',
+ 'Connection Terminated Due To Connection Timeout', // extra whitespace
+ ],
+ nonMatches: [
+ 'connection timeout',
+ 'connection terminated',
+ 'query timed out',
+ 'idle connection timeout',
+ '',
+ ],
+ },
+}
+
+describe('ERROR_PATTERNS registry', () => {
+ it('has a PATTERN_SAMPLES entry for every registered pattern (keep samples in sync)', () => {
+ for (const { ErrorClass } of ERROR_PATTERNS) {
+ expect(
+ PATTERN_SAMPLES,
+ `Add a PATTERN_SAMPLES entry for '${ErrorClass.name}'`
+ ).toHaveProperty(ErrorClass.name)
+ }
+ })
+
+ describe('per-pattern match correctness', () => {
+ for (const { ErrorClass, pattern } of ERROR_PATTERNS) {
+ const samples = PATTERN_SAMPLES[ErrorClass.name]
+ if (!samples) continue
+
+ describe(ErrorClass.name, () => {
+ it.each(samples.matches)('matches: %s', (msg) => {
+ expect(pattern.test(msg)).toBe(true)
+ })
+
+ it.each(samples.nonMatches)('does not match: %s', (msg) => {
+ expect(pattern.test(msg)).toBe(false)
+ })
+ })
+ }
+ })
+
+ describe('no message matches more than one pattern', () => {
+ const allSamples = Object.entries(PATTERN_SAMPLES).flatMap(([className, { matches }]) =>
+ matches.map((msg) => ({ msg, sourceClass: className }))
+ )
+
+ it.each(allSamples)('$sourceClass sample "$msg" matches exactly one pattern', ({ msg }) => {
+ const matched = ERROR_PATTERNS.filter(({ pattern }) => pattern.test(msg))
+ expect(matched.length).toBe(1)
+ })
+ })
+})
diff --git a/apps/studio/data/error-patterns.ts b/apps/studio/data/error-patterns.ts
new file mode 100644
index 00000000000..20b7542a6fd
--- /dev/null
+++ b/apps/studio/data/error-patterns.ts
@@ -0,0 +1,25 @@
+import { ConnectionTimeoutError } from 'types/api-errors'
+import type { ClassifiedError } from 'types/api-errors'
+import type { ResponseError } from 'types/base'
+
+type ErrorConstructor = new (
+ ...args: ConstructorParameters<typeof ResponseError>
+) => ClassifiedError
+
+export interface ErrorPattern {
+ pattern: RegExp
+ ErrorClass: ErrorConstructor
+}
+
+/**
+ * Maps each error class to its matching regex pattern.
+ * Using a Map guarantees each class can only appear once — duplicates are
+ * impossible by construction rather than only caught by tests.
+ */
+const ERROR_PATTERN_MAP = new Map<ErrorConstructor, RegExp>([
+ [ConnectionTimeoutError, /CONNECTION\s+TERMINATED\s+DUE\s+TO\s+CONNECTION\s+TIMEOUT/i],
+])
+
+export const ERROR_PATTERNS: ErrorPattern[] = Array.from(ERROR_PATTERN_MAP.entries()).map(
+ ([ErrorClass, pattern]) => ({ ErrorClass, pattern })
+)
diff --git a/apps/studio/data/fetchers.ts b/apps/studio/data/fetchers.ts
index 968d46851b0..1efd4ab910e 100644
--- a/apps/studio/data/fetchers.ts
+++ b/apps/studio/data/fetchers.ts
@@ -1,12 +1,14 @@
import * as Sentry from '@sentry/nextjs'
import { DEFAULT_PLATFORM_APPLICATION_NAME } from '@supabase/pg-meta/src/constants'
-import { IS_PLATFORM, getAccessToken } from 'common'
+import { getAccessToken, IS_PLATFORM } from 'common'
import { API_URL } from 'lib/constants'
import { uuidv4 } from 'lib/helpers'
import createClient from 'openapi-fetch'
import { ResponseError } from 'types'
+import { UnknownAPIResponseError } from 'types/api-errors'
import type { paths } from './api'
+import { ERROR_PATTERNS } from './error-patterns'
import { ErrorMetadata } from '@/types/base'
// generated from openapi-typescript
@@ -172,14 +174,24 @@ export const handleError = (error: unknown, options: HandleErrorOptions = {}): n
: undefined
if (errorMessage) {
- throw new ResponseError(
- errorMessage,
- errorCode,
- requestId,
- retryAfter,
- requestPathname,
- metadata
- )
+ const matched = ERROR_PATTERNS.find(({ pattern }) => pattern.test(errorMessage))
+ throw matched
+ ? new matched.ErrorClass(
+ errorMessage,
+ errorCode,
+ requestId,
+ retryAfter,
+ requestPathname,
+ metadata
+ )
+ : new UnknownAPIResponseError(
+ errorMessage,
+ errorCode,
+ requestId,
+ retryAfter,
+ requestPathname,
+ metadata
+ )
}
}
@@ -193,7 +205,7 @@ export const handleError = (error: unknown, options: HandleErrorOptions = {}): n
// throw a generic error if we don't know what the error is. The message is intentionally vague because it might show
// up in the UI.
- throw new ResponseError(undefined)
+ throw new UnknownAPIResponseError(undefined)
}
// [Joshen] The methods below are brought over from lib/common/fetch because we still need them
diff --git a/apps/studio/data/handleError.test.ts b/apps/studio/data/handleError.test.ts
new file mode 100644
index 00000000000..c0e086ff428
--- /dev/null
+++ b/apps/studio/data/handleError.test.ts
@@ -0,0 +1,98 @@
+import { ConnectionTimeoutError, UnknownAPIResponseError } from 'types/api-errors'
+import { ResponseError } from 'types/base'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@sentry/nextjs', () => ({ captureException: vi.fn() }))
+vi.mock('common', () => ({ IS_PLATFORM: false, getAccessToken: vi.fn() }))
+vi.mock('lib/constants', () => ({ API_URL: 'http://localhost' }))
+vi.mock('lib/helpers', () => ({ uuidv4: () => 'test-uuid' }))
+
+// Import after mocks are set up
+const { handleError } = await import('./fetchers')
+
+function throwAndCatch(error: unknown): ResponseError {
+ try {
+ handleError(error)
+ } catch (e) {
+ return e as ResponseError
+ }
+ throw new Error('handleError did not throw')
+}
+
+describe('handleError — error classification', () => {
+ beforeEach(() => vi.clearAllMocks())
+
+ describe('known patterns', () => {
+ it('classifies connection timeout via message field', () => {
+ const err = throwAndCatch({ message: 'CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT' })
+ expect(err).toBeInstanceOf(ConnectionTimeoutError)
+ expect((err as ConnectionTimeoutError).errorType).toBe('connection-timeout')
+ })
+
+ it('classifies connection timeout via msg field', () => {
+ const err = throwAndCatch({ msg: 'ERROR: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT' })
+ expect(err).toBeInstanceOf(ConnectionTimeoutError)
+ })
+
+ it('classification is case-insensitive', () => {
+ const err = throwAndCatch({ message: 'connection terminated due to connection timeout' })
+ expect(err).toBeInstanceOf(ConnectionTimeoutError)
+ })
+
+ it('classified error is still instanceof ResponseError', () => {
+ const err = throwAndCatch({ message: 'CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT' })
+ expect(err).toBeInstanceOf(ResponseError)
+ })
+ })
+
+ describe('unclassified errors', () => {
+ it('throws UnknownAPIResponseError for unmatched messages', () => {
+ const err = throwAndCatch({ message: 'something went wrong' })
+ expect(err).toBeInstanceOf(UnknownAPIResponseError)
+ expect(err).toBeInstanceOf(ResponseError)
+ })
+
+ it('throws UnknownAPIResponseError for empty message', () => {
+ const err = throwAndCatch({ message: '' })
+ expect(err).toBeInstanceOf(UnknownAPIResponseError)
+ })
+
+ it('throws UnknownAPIResponseError for null', () => {
+ const err = throwAndCatch(null)
+ expect(err).toBeInstanceOf(UnknownAPIResponseError)
+ })
+
+ it('throws UnknownAPIResponseError for non-object', () => {
+ const err = throwAndCatch('raw string error')
+ expect(err).toBeInstanceOf(UnknownAPIResponseError)
+ })
+ })
+
+ describe('field preservation', () => {
+ it('preserves all ResponseError fields on classified errors', () => {
+ const err = throwAndCatch({
+ message: 'CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT',
+ code: 503,
+ requestId: 'req-abc',
+ retryAfter: 30,
+ requestPathname: '/rest/v1/table',
+ })
+ expect(err.message).toBe('CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT')
+ expect(err.code).toBe(503)
+ expect(err.requestId).toBe('req-abc')
+ expect(err.retryAfter).toBe(30)
+ expect(err.requestPathname).toBe('/rest/v1/table')
+ })
+
+ it('preserves all ResponseError fields on unclassified errors', () => {
+ const err = throwAndCatch({ message: 'some error', code: 500, requestId: 'req-xyz' })
+ expect(err.code).toBe(500)
+ expect(err.requestId).toBe('req-xyz')
+ })
+
+ it('msg field takes priority over message field for error text', () => {
+ const err = throwAndCatch({ msg: 'from msg field', message: 'from message field' })
+ expect(err.message).toBe('from msg field')
+ })
+ })
+})
diff --git a/apps/studio/lib/error-reporting.ts b/apps/studio/lib/error-reporting.ts
index bf634e5e9af..ec0b23788c6 100644
--- a/apps/studio/lib/error-reporting.ts
+++ b/apps/studio/lib/error-reporting.ts
@@ -51,7 +51,7 @@ export function captureCriticalError(
return
}
- handleUnknownError(error, context)
+ handleUnknownAPIResponseError(error, context)
}
function handleResponseError(error: ResponseError, context: string) {
@@ -85,7 +85,7 @@ function handleError(error: Error, context: string) {
})
}
-function handleUnknownError(error: unknown, context: string) {
+function handleUnknownAPIResponseError(error: unknown, context: string) {
if (
error &&
typeof error === 'object' &&
diff --git a/apps/studio/types/api-errors.ts b/apps/studio/types/api-errors.ts
new file mode 100644
index 00000000000..3b902510801
--- /dev/null
+++ b/apps/studio/types/api-errors.ts
@@ -0,0 +1,36 @@
+import { ResponseError } from './base'
+import type { ErrorMetadata } from './base'
+
+export type KnownErrorType = 'connection-timeout'
+
+export class ConnectionTimeoutError extends ResponseError {
+ readonly errorType = 'connection-timeout' as const
+
+ constructor(
+ message: string | undefined,
+ code?: number,
+ requestId?: string,
+ retryAfter?: number,
+ requestPathname?: string,
+ metadata?: ErrorMetadata
+ ) {
+ super(message, code, requestId, retryAfter, requestPathname, metadata)
+ }
+}
+
+export class UnknownAPIResponseError extends ResponseError {
+ readonly errorType = 'unknown' as const
+
+ constructor(
+ message: string | undefined,
+ code?: number,
+ requestId?: string,
+ retryAfter?: number,
+ requestPathname?: string,
+ metadata?: ErrorMetadata
+ ) {
+ super(message, code, requestId, retryAfter, requestPathname, metadata)
+ }
+}
+
+export type ClassifiedError = ConnectionTimeoutError | UnknownAPIResponseError
diff --git a/apps/studio/types/base.ts b/apps/studio/types/base.ts
index 3981a57b14d..7d2d5757d45 100644
--- a/apps/studio/types/base.ts
+++ b/apps/studio/types/base.ts
@@ -100,6 +100,7 @@ export class ResponseError extends Error {
retryAfter?: number
requestPathname?: string
metadata?: CostMetadata
+ errorType?: string
constructor(
message: string | undefined,
diff --git a/packages/common/telemetry-constants.ts b/packages/common/telemetry-constants.ts
index f6f0f40c1e6..367fd1cd9f6 100644
--- a/packages/common/telemetry-constants.ts
+++ b/packages/common/telemetry-constants.ts
@@ -2791,7 +2791,7 @@ export interface RequestUpgradeSubmittedEvent {
/**
* Triggered when a Studio error UI element is displayed (mounted).
- * This includes error Admonitions and Toast notifications.
+ * This includes error Admonitions, Toast notifications, and ErrorDisplay components.
*
* @group Events
* @source studio
@@ -2802,7 +2802,69 @@ export interface DashboardErrorCreatedEvent {
/**
* Source of the error
*/
- source?: 'admonition' | 'toast'
+ source?: 'admonition' | 'toast' | 'error_display'
+ /**
+ * Type of error matched (for error_display source)
+ */
+ errorType?: string
+ /**
+ * Whether troubleshooting steps are available (for error_display source)
+ */
+ hasTroubleshooting?: boolean
+ }
+ groups: TelemetryGroups
+}
+
+/**
+ * Triggered when the inline error troubleshooter is shown to the user.
+ *
+ * @group Events
+ * @source studio
+ */
+export interface InlineErrorTroubleshooterExposedEvent {
+ action: 'inline_error_troubleshooter_exposed'
+ properties: {
+ /** ID of the matched error mapping */
+ errorType: string
+ }
+ groups: TelemetryGroups
+}
+
+/**
+ * Triggered when a user opens or closes a troubleshooting accordion step.
+ *
+ * @group Events
+ * @source studio
+ */
+export interface InlineErrorTroubleshooterStepClickedEvent {
+ action: 'inline_error_troubleshooter_step_clicked'
+ properties: {
+ /** ID of the matched error mapping */
+ errorType: string
+ /** Step number that was clicked (1, 2, 3, ...) — null when a step is collapsed */
+ step: number | null
+ /** Title of the step that was clicked */
+ stepTitle?: string
+ /** Whether the step was opened (true) or closed (false) */
+ expanded: boolean
+ }
+ groups: TelemetryGroups
+}
+
+/**
+ * Triggered when a user clicks an action within the inline error troubleshooter.
+ * Covers all CTAs including the contact support link.
+ *
+ * @group Events
+ * @source studio
+ */
+export interface InlineErrorTroubleshooterActionClickedEvent {
+ action: 'inline_error_troubleshooter_action_clicked'
+ properties: {
+ /** ID of the matched error mapping */
+ errorType: string
+ /** Which CTA was clicked */
+ ctaType: 'restart_db' | 'troubleshooting_guide' | 'ask_ai' | 'contact_support'
}
groups: TelemetryGroups
}
@@ -3104,6 +3166,9 @@ export type TelemetryEvent =
| RequestUpgradeModalOpenedEvent
| RequestUpgradeSubmittedEvent
| DashboardErrorCreatedEvent
+ | InlineErrorTroubleshooterExposedEvent
+ | InlineErrorTroubleshooterStepClickedEvent
+ | InlineErrorTroubleshooterActionClickedEvent
| IntegrationInstallCompletedEvent
| IntegrationInstallSubmittedEvent
| IntegrationUninstallSubmittedEvent
diff --git a/packages/ui-patterns/package.json b/packages/ui-patterns/package.json
index 8e1894b832a..7090d080373 100644
--- a/packages/ui-patterns/package.json
+++ b/packages/ui-patterns/package.json
@@ -222,6 +222,10 @@
"import": "./src/CommandMenu/prepackaged/Support.tsx",
"types": "./src/CommandMenu/prepackaged/Support.tsx"
},
+ "./CommandMenu/prepackaged/ThemeSwitcher.test": {
+ "import": "./src/CommandMenu/prepackaged/ThemeSwitcher.test.tsx",
+ "types": "./src/CommandMenu/prepackaged/ThemeSwitcher.test.tsx"
+ },
"./CommandMenu/prepackaged/ThemeSwitcher": {
"import": "./src/CommandMenu/prepackaged/ThemeSwitcher.tsx",
"types": "./src/CommandMenu/prepackaged/ThemeSwitcher.tsx"
@@ -302,10 +306,30 @@
"import": "./src/EmptyStatePresentational/index.tsx",
"types": "./src/EmptyStatePresentational/index.tsx"
},
+ "./ErrorDisplay/ErrorDisplay": {
+ "import": "./src/ErrorDisplay/ErrorDisplay.tsx",
+ "types": "./src/ErrorDisplay/ErrorDisplay.tsx"
+ },
+ "./ErrorDisplay/ErrorDisplay.types": {
+ "import": "./src/ErrorDisplay/ErrorDisplay.types.ts",
+ "types": "./src/ErrorDisplay/ErrorDisplay.types.ts"
+ },
+ "./ErrorDisplay": {
+ "import": "./src/ErrorDisplay/ErrorDisplay.tsx",
+ "types": "./src/ErrorDisplay/ErrorDisplay.tsx"
+ },
"./ExpandableVideo": {
"import": "./src/ExpandableVideo/index.tsx",
"types": "./src/ExpandableVideo/index.tsx"
},
+ "./FilterBar/CommandListItem": {
+ "import": "./src/FilterBar/CommandListItem.tsx",
+ "types": "./src/FilterBar/CommandListItem.tsx"
+ },
+ "./FilterBar/DefaultCommandList.helpers": {
+ "import": "./src/FilterBar/DefaultCommandList.helpers.tsx",
+ "types": "./src/FilterBar/DefaultCommandList.helpers.tsx"
+ },
"./FilterBar/DefaultCommandList": {
"import": "./src/FilterBar/DefaultCommandList.tsx",
"types": "./src/FilterBar/DefaultCommandList.tsx"
@@ -330,6 +354,10 @@
"import": "./src/FilterBar/FilterGroup.tsx",
"types": "./src/FilterBar/FilterGroup.tsx"
},
+ "./FilterBar/OperatorSymbolBadge": {
+ "import": "./src/FilterBar/OperatorSymbolBadge.tsx",
+ "types": "./src/FilterBar/OperatorSymbolBadge.tsx"
+ },
"./FilterBar/hooks.test": {
"import": "./src/FilterBar/hooks.test.ts",
"types": "./src/FilterBar/hooks.test.ts"
@@ -342,6 +370,10 @@
"import": "./src/FilterBar/index.ts",
"types": "./src/FilterBar/index.ts"
},
+ "./FilterBar/menuItems.test": {
+ "import": "./src/FilterBar/menuItems.test.ts",
+ "types": "./src/FilterBar/menuItems.test.ts"
+ },
"./FilterBar/menuItems": {
"import": "./src/FilterBar/menuItems.ts",
"types": "./src/FilterBar/menuItems.ts"
@@ -350,10 +382,18 @@
"import": "./src/FilterBar/types.ts",
"types": "./src/FilterBar/types.ts"
},
+ "./FilterBar/useAIFilter": {
+ "import": "./src/FilterBar/useAIFilter.ts",
+ "types": "./src/FilterBar/useAIFilter.ts"
+ },
"./FilterBar/useCommandHandling": {
"import": "./src/FilterBar/useCommandHandling.ts",
"types": "./src/FilterBar/useCommandHandling.ts"
},
+ "./FilterBar/useCommandMenu": {
+ "import": "./src/FilterBar/useCommandMenu.ts",
+ "types": "./src/FilterBar/useCommandMenu.ts"
+ },
"./FilterBar/useKeyboardNavigation": {
"import": "./src/FilterBar/useKeyboardNavigation.ts",
"types": "./src/FilterBar/useKeyboardNavigation.ts"
@@ -422,6 +462,10 @@
"import": "./src/McpUrlBuilder/utils/getMcpButtonData.ts",
"types": "./src/McpUrlBuilder/utils/getMcpButtonData.ts"
},
+ "./McpUrlBuilder/utils/getMcpIconSrc": {
+ "import": "./src/McpUrlBuilder/utils/getMcpIconSrc.ts",
+ "types": "./src/McpUrlBuilder/utils/getMcpIconSrc.ts"
+ },
"./McpUrlBuilder/utils/getMcpUrl": {
"import": "./src/McpUrlBuilder/utils/getMcpUrl.ts",
"types": "./src/McpUrlBuilder/utils/getMcpUrl.ts"
@@ -430,6 +474,10 @@
"import": "./src/MetricCard/index.tsx",
"types": "./src/MetricCard/index.tsx"
},
+ "./MobileSheetNav/MobileSheetNav.test": {
+ "import": "./src/MobileSheetNav/MobileSheetNav.test.tsx",
+ "types": "./src/MobileSheetNav/MobileSheetNav.test.tsx"
+ },
"./MobileSheetNav/MobileSheetNav": {
"import": "./src/MobileSheetNav/MobileSheetNav.tsx",
"types": "./src/MobileSheetNav/MobileSheetNav.tsx"
@@ -450,6 +498,10 @@
"import": "./src/MultiSelectDeprecated/index.tsx",
"types": "./src/MultiSelectDeprecated/index.tsx"
},
+ "./MultipleCodeBlock": {
+ "import": "./src/MultipleCodeBlock/index.tsx",
+ "types": "./src/MultipleCodeBlock/index.tsx"
+ },
"./PageContainer": {
"import": "./src/PageContainer/index.tsx",
"types": "./src/PageContainer/index.tsx"
@@ -582,10 +634,6 @@
"import": "./src/admonition.tsx",
"types": "./src/admonition.tsx"
},
- "./MultipleCodeBlock": {
- "import": "./src/MultipleCodeBlock/index.tsx",
- "types": "./src/MultipleCodeBlock/index.tsx"
- },
"./consent": {
"import": "./src/consent.tsx",
"types": "./src/consent.tsx"
diff --git a/packages/ui-patterns/src/ErrorDisplay/ErrorDisplay.tsx b/packages/ui-patterns/src/ErrorDisplay/ErrorDisplay.tsx
new file mode 100644
index 00000000000..bbdd536a7ea
--- /dev/null
+++ b/packages/ui-patterns/src/ErrorDisplay/ErrorDisplay.tsx
@@ -0,0 +1,90 @@
+'use client'
+
+import { HelpCircle } from 'lucide-react'
+import { forwardRef, useEffect, useRef } from 'react'
+import { Card, CardHeader, cn } from 'ui'
+
+import { WarningIcon } from '../admonition'
+import type { ErrorDisplayProps, SupportFormParams } from './ErrorDisplay.types'
+
+export type { SupportFormParams } from './ErrorDisplay.types'
+
+function buildSupportUrl(params?: SupportFormParams) {
+ if (!params) return '/support/new'
+ const entries = Object.entries(params).filter(([, v]) => v !== undefined && v !== '')
+ if (entries.length === 0) return '/support/new'
+ return `/support/new?${new URLSearchParams(entries as [string, string][]).toString()}`
+}
+
+export const ErrorDisplay = forwardRef<HTMLDivElement, ErrorDisplayProps>(
+ (
+ {
+ title,
+ errorMessage,
+ supportFormParams,
+ supportLabel = 'Contact support',
+ children,
+ className,
+ icon,
+ onRender,
+ onSupportClick,
+ ...props
+ },
+ ref
+ ) => {
+ const hasFired = useRef(false)
+ useEffect(() => {
+ if (hasFired.current) return
+ hasFired.current = true
+ onRender?.()
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [])
+
+ const supportUrl = buildSupportUrl(supportFormParams)
+
+ return (
+ <Card
+ ref={ref}
+ className={cn('rounded-lg border border-default', className)}
+ role="alert"
+ aria-labelledby="error-display-title"
+ {...props}
+ >
+ <CardHeader className="flex-row items-center gap-2.5 space-y-0 p-3">
+ <div className="bg-warning p-1 text-background rounded-md">
+ {icon ?? <WarningIcon className="w-3 h-3" />}
+ </div>
+ <h3 id="error-display-title" className="text-sm text-foreground mt-0">
+ {title}
+ </h3>
+ </CardHeader>
+
+ <div className="px-4 py-3 bg-warning-200 border-y border-warning-500">
+ <pre className="text-xs font-mono text-warning-600 whitespace-pre-wrap break-words overflow-auto max-h-32">
+ {errorMessage}
+ </pre>
+ </div>
+
+ {children && <div>{children}</div>}
+
+ <div className="px-3 py-2 border-t border-default flex items-center gap-2">
+ <div className="flex-shrink-0">
+ <HelpCircle className="h-4 w-4 text-foreground-muted" />
+ </div>
+ <span className="text-sm text-foreground-light">Need help?</span>
+ <a
+ href={supportUrl}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="text-sm text-foreground flex-shrink-0 underline hover:text-foreground-light transition-colors"
+ onClick={onSupportClick}
+ >
+ {supportLabel}
+ </a>
+ </div>
+ </Card>
+ )
+ }
+)
+
+ErrorDisplay.displayName = 'ErrorDisplay'
diff --git a/packages/ui-patterns/src/ErrorDisplay/ErrorDisplay.types.ts b/packages/ui-patterns/src/ErrorDisplay/ErrorDisplay.types.ts
new file mode 100644
index 00000000000..659141af524
--- /dev/null
+++ b/packages/ui-patterns/src/ErrorDisplay/ErrorDisplay.types.ts
@@ -0,0 +1,67 @@
+import { ComponentPropsWithoutRef, ReactNode } from 'react'
+
+export interface SupportFormParams {
+ projectRef?: string
+ orgSlug?: string
+ category?: string
+ subject?: string
+ message?: string
+ error?: string
+ /** Sentry event ID */
+ sid?: string
+}
+
+export interface ErrorDisplayProps extends ComponentPropsWithoutRef<'div'> {
+ /**
+ * Title displayed in the header with warning icon
+ * @example "Failed to retrieve tables"
+ */
+ title: string
+
+ /**
+ * Error message displayed in monospace code block style
+ * @example "ERROR: FAILED TO RUN SQL QUERY: CONNECTION TERMINATED DUE TO CONNECTION TIMEOUT."
+ */
+ errorMessage: string
+
+ /**
+ * Typed params for the support form URL. The component builds the URL automatically.
+ * The "Contact support" footer is always shown.
+ * @example { projectRef: 'my-project' }
+ */
+ supportFormParams?: SupportFormParams
+
+ /**
+ * Text for the support link
+ * @default "Contact support"
+ */
+ supportLabel?: string
+
+ /**
+ * Children slot for accordion-style troubleshooting steps
+ * Typically contains TroubleshootingAccordion or similar content
+ */
+ children?: ReactNode
+
+ /**
+ * Additional CSS classes for the root container
+ */
+ className?: string
+
+ /**
+ * Custom icon to display in the header. Defaults to a filled warning triangle SVG.
+ */
+ icon?: ReactNode
+
+ /**
+ * Callback fired when the component is rendered
+ * Useful for tracking error display events
+ */
+ onRender?: () => void
+
+ /**
+ * Callback fired when the contact support link is clicked
+ * Useful for tracking support escalations
+ */
+ onSupportClick?: () => void
+}
diff --git a/packages/ui-patterns/src/admonition.tsx b/packages/ui-patterns/src/admonition.tsx
index 5af083b26d6..6700794f61b 100644
--- a/packages/ui-patterns/src/admonition.tsx
+++ b/packages/ui-patterns/src/admonition.tsx
@@ -55,11 +55,11 @@ const InfoIcon = () => (
</svg>
)
-const WarningIcon = () => (
+export const WarningIcon = ({ className }: { className?: string }) => (
<svg
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 22 20"
- className="w-6 h-6"
+ className={cn('w-6 h-6', className)}
fill="currentColor"
>
<path