---
id: react-error-boundary
title: React Error Boundary 패턴
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [react, error-handling, resilience, vibe-coding]
tech_stack: { language: "TypeScript / React 18+", applicable_to: ["Web", "React Native"] }
applied_in: []
aliases: [componentDidCatch, fallback UI, react-error-boundary]
---

# React Error Boundary 패턴

> render / lifecycle / constructor 에서 throw 된 에러를 잡아 fallback UI 표시. **이벤트 핸들러 / async / setTimeout 에러는 안 잡음** — 그건 일반 try/catch.

## 📖 핵심 개념
- Class component 만 가능 (Hook 형태 없음). `react-error-boundary` 라이브러리 함수 컴포넌트 wrapper.
- 경계마다 isolated fallback. 트리 일부만 죽고 나머지 살아남기.

## 💻 코드 패턴

### react-error-boundary 라이브러리
```tsx
import { ErrorBoundary } from 'react-error-boundary';

function Fallback({ error, resetErrorBoundary }: any) {
  return <div role="alert">
    <p>오류: {error.message}</p>
    <button onClick={resetErrorBoundary}>다시 시도</button>
  </div>;
}

<ErrorBoundary FallbackComponent={Fallback}
  onError={(err, info) => sendToSentry(err, info)}
  onReset={() => resetCacheKeys()}>
  <Dashboard />
</ErrorBoundary>
```

### Suspense + ErrorBoundary 조합
```tsx
<ErrorBoundary FallbackComponent={Fallback}>
  <Suspense fallback={<Spinner />}>
    <UserProfile id={id} />
  </Suspense>
</ErrorBoundary>
```

## 🤔 의사결정 기준
| 영역 | Error Boundary | try/catch |
|---|---|---|
| 컴포넌트 render 중 throw | ✅ | — |
| useEffect 안의 async 에러 | ❌ | ✅ |
| 이벤트 핸들러 (onClick) | ❌ | ✅ |
| Suspense fallback 안의 throw | ✅ | — |
| Server-side rendering 에러 | 부분 (Next.js error.tsx) | — |
| 전역 unhandled rejection | ❌ | window.onunhandledrejection |

## ❌ 안티패턴
- **앱 루트에 하나만**: 한 컴포넌트 사고 = 전체 화면 흰색. 화면 영역마다 boundary.
- **fallback 에서 동일 에러 다시 throw**: 무한 루프.
- **에러 silently 삼킴**: 로깅 / 모니터링 (Sentry/Datadog) 필수.
- **이벤트 핸들러 에러를 boundary 가 잡을 거라 가정**: 안 잡힘. 핸들러는 try/catch.
- **resetErrorBoundary 호출 시 같은 에러 재발생**: 원인을 안 고치면 다시 throw. cache key reset / state reset 필수.
- **production 에서 error.message 그대로 노출**: 보안 위험. 일반 메시지 + 내부 로깅 분리.

## 🤖 LLM 활용 힌트
- "data fetching 자식 마다 ErrorBoundary + Suspense 페어" 패턴 강제.
- onError 에서 Sentry 등 외부 서비스 보고 명시.

## 🔗 관련 문서
- [[React_Suspense_for_Data]]
- [[Error_Handling_Result_vs_Throw]]