studio-error-handling

Studio のエラー処理パターン

ドキュメントとコード例の全文：apps/studio/components/interfaces/ErrorHandling/README.md

仕組み

分類はデータレイヤーで行われます。data/fetchers.ts の handleError が、エラーメッセージを ERROR_PATTERNS と照合し、一致したエラーサブクラス（例：ConnectionTimeoutError extends ResponseError）をスローします。コンポーネント（ErrorMatcher）はインスタンスから errorType を読み取り、O(1) で検索します。正規表現による照合は行いません。

handleError() → throws ConnectionTimeoutError → React Query catches → ErrorMatcher reads errorType → renders troubleshooting

主なファイル

ファイル	目的
data/error-patterns.ts	{ pattern, ErrorClass } の配列。正規表現はここにあります
types/api-errors.ts	エラークラス、KnownErrorType ユニオン、ClassifiedError 型
ErrorMatcher.tsx	コンポーネント。errorType を読み取り、マッピングを検索して描画します
error-mappings.tsx	Record<KnownErrorType, { id, Troubleshooting: ComponentType }>
errorMappings/ConnectionTimeout.tsx	トラブルシューティングコンポーネントのリファレンス
TroubleshootingSections.tsx	再利用可能なアコーディオンセクションコンポーネント
TroubleshootingAccordion.tsx	テレメトリーを含むアコーディオンラッパー

使用するコンポーネント

状況	使用するもの
クエリが失敗し、ページ／セクションでデータを描画できない場合（デフォルトのケース。Studio の大半はこちら）	components/ui/AlertError の AlertError
エラーが独自のトラブルシューティング手順を持つ分類済みの型である可能性がある場合（例：接続タイムアウト）	components/interfaces/ErrorHandling/ErrorMatcher の ErrorMatcher。未分類の場合に備えて fallback を渡します
ミューテーションが失敗した場合	ミューテーションフックのデフォルトの onError トースト（sonner の toast.error）。アラートは描画しないでください（studio-queries を参照）

AlertError（デフォルト）

エラーメッセージ、一般的な「更新を試す／サポートに問い合わせる」手順、および projectRef、subject、エラーメッセージがあらかじめ入力されたサポートに問い合わせるボタンを含む、警告用の Admonition を描画します。

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

• subject は人が読めるタイトルで、Failed to <verb> <thing> の形式にします。プロジェクトのコンテキスト内では projectRef を渡し、サポートフォームにあらかじめ入力されるようにします。
• error は React Query のエラーオブジェクト（message を持つものなら何でも）です。503 のレスポンスは自動的に言い換えられます。
• 再試行ボタンや移動ボタンには additionalActions を使用します。hideContactSupport を使うのは、サポートでは実際に解決できない場合（ユーザー入力エラーなど）に限ってください。
• ページ／セクションの主要データには早期リターン形式を使います。ページの残りをブロックしない補助パネルには、インラインの {isError && <AlertError … />} を使用します。

ErrorMatcher（分類済みエラー）

データレイヤーがエラーを専用のトラブルシューティング UI を持つ KnownErrorType に分類する可能性がある場合に使用します。エラーインスタンスから errorType を読み取り、対応する Troubleshooting コンポーネントを描画します。マッピングがない場合は fallback を描画します。現在はテーブルエディターのサイドバーで使用されています。AlertError の一般的な代替としてではなく、新しいエラー型のトラブルシューティングを追加する際に使用してください。

ErrorMatcher の使用方法

React Query からのエラーオブジェクト全体を渡してください。error.message ではありません。

{
  isError && (
    <ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{ projectRef }} />
  )
}

してはいけないこと

• error.message を ErrorMatcher に渡さないでください。クラスが保持されるよう、error オブジェクト全体を渡してください。
• error-mappings.tsx に正規表現パターンを記述しないでください。パターンは data/error-patterns.ts に記述します。
• Object.assign を使って errorType を設定しないでください。適切なサブクラスをスローしてください。
• サポート用に URL 文字列をそのまま渡さないでください。supportFormParams={{ projectRef }} を使用してください。
• エラーマッピング内にページタイトルを記述しないでください。<ErrorMatcher> の呼び出し元に記述します。
• トラブルシューティングコンポーネントにコールバックプロパティ（onDebugWithAI、onRestartProject）を追加しないでください。代わりに、コンポーネント内でフックを使用してください。