개념 설명
Next.js App Router에서는 에러 핸들링을 위해 error.tsx라는 특수 파일을 도입하여 React Error Boundary를 자동으로 설정해 주는 기능임. 특정 세그먼트(Route Segment) 내에서 예상치 못한 런타임 에러가 발생했을 때, 전체 페이지가 중단되는 것을 방지하고 사용자에게 대체 UI(Fallback UI)를 보여주는 역할 수행.
클라이언트 컴포넌트 환경에서 동작하며, 에러 발생 시 해당 에러 정보(error)와 다시 시도할 수 있는 함수(reset)를 프롭스로 전달받음. 이를 통해 애플리케이션의 가용성을 높이고 사용자 경험을 개선하는 데 결정적인 기여를 함.
사용 상황 예시
- API 호출 실패: 외부 데이터 페칭 중 500 에러나 네트워크 장애가 발생하여 데이터를 불러올 수 없는 상황
- 데이터 파싱 오류: 서버에서 전달받은 JSON 데이터의 형식이 예상과 달라 렌더링 중 런타임 에러가 발생하는 경우
- 권한 없는 접근: 특정 컴포넌트에서 렌더링 도중 인증 정보 부족이 감지되어 에러를 던져야 하는 상황
기본 문법
error.tsx는 반드시 'use client' 지시어를 포함해야 하며, 다음과 같은 기본 구조를 가짐.
TypeScript
'use client' // 에러 경계는 클라이언트 컴포넌트여야 함
import { useEffect } from 'react'
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
useEffect(() => {
// 에러 로그 기록 (Sentry 등 외부 서비스 연동)
console.error(error)
}, [error])
return (
<div>
<h2>문제가 발생함!</h2>
<button onClick={() => reset()}>다시 시도</button>
</div>
)
}자주 하는 실수
- 서버 컴포넌트 시도:
error.tsx를 서버 컴포넌트로 작성하여 실행 에러가 발생하는 경우 (반드시 'use client' 명시 필요) - Layout 에러 캐치 시도: 같은 경로의
layout.tsx에서 발생한 에러는 해당 경로의error.tsx에서 잡지 못함 (상위 경로의error.tsx나global-error.tsx사용 필요) - reset 함수 오용:
reset()은 클라이언트 측 재렌더링을 시도하지만, 서버 데이터가 변경되지 않았다면 동일한 에러가 반복될 수 있음을 간과하는 경우
핵심 요약
- 에러 발생 시 전체 페이지 붕괴를 방지하는 클라이언트 기반 Error Boundary 기능
- 'use client' 선언 필수 및 상위 레이아웃 에러 처리는 global-error.tsx 활용 권장
- 에러 로깅과 사용자 재시도(reset) 기능을 통한 최적화된 사용자 경험 제공
출처: 한 입 크기로 잘라먹는 Next.js(v15)
