Agent Skills › supabase/supabase › studio-error-handling

studio-error-handling

GitHub

定义 Supabase Studio 的错误处理与展示模式，涵盖错误分类、UI 渲染及故障排查步骤，指导如何正确集成 ErrorMatcher 组件。

.claude/skills/studio-error-handling/SKILL.md supabase/supabase

触发场景

需要显示 API 请求或查询失败的 UI 提示为新的错误类型添加故障排查步骤从错误状态接入 AI 助手调试按钮

安装

npx skills add supabase/supabase --skill studio-error-handling -g -y

更多选项

非标准路径

npx skills add https://github.com/supabase/supabase/tree/master/.claude/skills/studio-error-handling -g -y

不安装直接使用

npx skills use supabase/supabase@studio-error-handling

指定 Agent (Claude Code)

npx skills add supabase/supabase --skill studio-error-handling -a claude-code -g -y

安装 repo 全部 skill

npx skills add supabase/supabase --all -g -y

预览 repo 内 skill

npx skills add supabase/supabase --list

SKILL.md

Frontmatter

{
    "name": "studio-error-handling",
    "description": "Error display and troubleshooting pattern for Supabase Studio. Use when showing a failed API request or query error in the UI (AlertError, toast, inline message), adding 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:

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