🛡️ Next.js 8장: Error Handling — 내 앱을 지키는 최후의 방어선

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 error.tsx의 마법: Error Boundary의 진화 🟢
• 🌱 에러의 지역화 (Localization) 전략 🟡
• 🎯 한 걸음 더: 컴포넌트 단위의 정밀 타격 에러 처리
• 🚨 서버 다운 최후의 보루: global-error.tsx 🔴
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분(전체) / 핵심 파트만: 8분

🗺️ 이 문서의 흐름
RSC 에러 에러 전파의 위험성 → error.tsx 방어막 원리 → 에러를 잘게 부수어 격리하는 시니어 아키텍처

🎯 이 문서를 다 읽으면 할 수 있는 것

• try-catch 로만 과잉 적용하던 취약한 코드에서 벗어나, 선언형 지시자 파일(error.tsx) 하나로 폴더 단위 에러를 우아하게 제압할 수 있다.
• 에러가 난 곳만 버튼으로 reset() 함수를 불려 페이지 강제 새로고침 없이 해당 파편 컴포넌트만 회복시키는 고급 렌더 컨트롤을 구현할 수 있다.

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(새로 온 주니어): "어? 사이드바에서 유저 랭킹 가져오는 API 하나 터졌다고 사이트 전체가 엄청 무서운 에러 스크린으로 도배되면서 뻗어버려요! 멀쩡한 다른 게시판 글들도 안 보이고 완전 마비예요! 😭"
• 영호(FE 리드): "영철 님... React 트리는 컴포넌트 하나가 에러로 오류가 발생하면 자기 부모 형제까지 다 중단되는 연쇄 중단 법칙이 있단 말이에요! 넥스트가 제공하는 방화벽(error.tsx) 파일만 툭 던져놨어도 랭킹 영역 하나만 우아하게 중단되고 다른 영역은 계속 동작했을 텐데!"

🤔 왜 알아야 하는가

오래된 SPA 방식에서는 API 에러가 나면 주로 catch 안에서 alert("에러입니다") 띄우고 끝났어.
하지만 Next.js의 대세인 React Server Component(RSC) 세상은 완전히 달라.
서버에서 조립되던 HTML 쪼가리들이 await db() 하다가 1초 뒤에 펑! 하고 오류가 나버려(Exception Throw).

Next.js 서버가 에러를 뿜으면 이 에러가 걷잡을 수 없이 상위 부모 컴포넌트로 역류하며 올라가. 단단한 뚜껑(Error Boundary)으로 어느 중간 지점에서 딱! 막아내지 않으면, 결국 최상단 루트 레이아웃마저 중단시키며 앱 전체가 새하얀 "Internal Server Error" 화면으로 돌변해.
그 작은 찌꺼기 에러 하나 때문에 멀쩡하게 돌아가던 사이트 메인 GNB와 사이드탭마저 증발해버리는 것은 위험한 UX(사용자 경험)야.

이 거대한 도미노 붕괴를 막아내는 넥스트 파일 시스템 예약어가 바로 error.tsx야.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면? (영수네 국밥집의 방화 셔터)

❌ 과거 (영철이의 칸막이 없는 식당)
주방 화구(API) 중 하나가 과열되어 불이 났어. 그런데 방수 격벽이나 칸막이가 하나도 없네?
불길이 화장실을 넘어 복도로 가고, 카운터까지 번지더니 순식간에 식당 전체(앱 전체) 가 타버려 멸망해.

✅ 현재 (error.tsx 선언형 방화 셔터)
주방장 영호 님이 주방 구역마다, 그리고 복도 입구마다 튼튼한 철제 셔터(방화 격벽 = error.tsx) 를 하나씩 설치해뒀어.
주방에서 불이 나면 삐용삐용! 소리와 함께 그 즉시 제일 가까운 셔터가 철컹! 하고 내려가서 불길을 가둬버려.
주방 일부 구역은 수리하느라 못 쓰겠지만(fallback 에러 UI) , 홀에서 국밥을 먹던 손님들은 아무 일 없다는 듯 맛있게 식사를 계속할 수 있어!

🧩 error.tsx의 마법: Error Boundary의 진화 🟢

기존 React 개발자들이 Error Boundary 랩핑기(Class Component)를 손수 짜며 고통받았다면, Next.js에서는 그냥 오류가 발생할 것 같은 폴더에 저 이름의 파일을 "만들기만 하면" 돼.

1) 방어막 기본 원리

app/dashboard/ 페이지가 오류가 발생한다고 가정하자.

app/
 └─ dashboard/
     ├─ layout.tsx  (1. 이 파일마저 오류가 발생하면 더 위쪽으로 역류해 올라가버린다)
     ├─ error.tsx   (2. 강력한 에러 경계! 이 파일이 존재하는 한 page.tsx의 에러는 문 밖을 나가지 못함)
     └─ page.tsx    (3. 에러 유발자! 내부에서 DB 조회하다 뻗음)

만약 오류가 발생하면, Next.js가 page.tsx UI를 렌더 박스에서 싹 덜어내버리고, 그 자리에 니가 error.tsx 파일에서 리턴시킨 Fallback UI 컴포넌트로 쏙! 대체해버려.

2) 클라이언트 컴포넌트 선언 강제 규약 (use client)

⚠️ 가장 초보자들이 많이 하는 실수 1순위. error.tsx는 무조건 첫 줄에 'use client' 지시자 가 달려 있어야 해.

왜일까? 에러는 언제 어느 시나리오에서 오류가 발생할지 몰라.
서버에서 HTML을 조립하다가(RSC) 오류가 발생할 수도 있고, 내 폰에서 onClick 누르다 런타임에(Client) 오류가 발생할 수도 있지. 모든 에러(Server, Client 무관)를 잡아채고 브라우저 콘솔에서 Recovery(복구 버튼) 동작까지 지원하려면 이 파일 자체가 클라이언트 베이스에서 구동되어야 하기 때문이야.

// app/dashboard/error.tsx
'use client' // ❤️ 잊으면 빌드 에러 남!
 
import { useEffect } from 'react'
 
export default function DashboardError({
  error,
  reset,
}: {
  error: Error & { digest?: string } // 에러 정보 객체
  reset: () => void // 실패했던 page.tsx 영역을 재렌더링 시도하는 마법의 버튼
}) {
  useEffect(() => {
    // Sentry, Datadog 등으로 몰래 에러 전문을 수집해 올린다
    console.error('앗! 대시보드에서 엄청난 에러가:', error)
  }, [error])
 
  return (
    <div className="bg-red-50 p-4 rounded-md">
      <h2>뭔가 단단히 잘못됐어요. (방수 격벽 닫힘)</h2>
      {/* 다시 시도하기 버튼 클릭 시, 컴포넌트만 강제로 재요청 (전체 새로고침 무관) */}
      <button onClick={() => reset()}>
        문 다시 한 번 열어보기
      </button>
    </div>
  )
}

🌱 에러의 지역화 (Localization) 전략 🟡

이제 면접 단골 질문이자 시니어 아키텍처의 핵심 도메인으로 들어가볼까?
"레이아웃 안에서 서로 다른 두 개의 API를 불렀는데, 하나만 터졌어. 레이아웃과 정상 API 뷰는 살릴 수 있는가?"

❌ 영철이의 통짜 에러 처리 (상위 루트로 몽땅 에러 떠넘기기)

영철이는 그냥 귀찮아서 루트 폴더(app/error.tsx) 하나만 만들어 뒀어.
그래서 덜 중요한 사이드바 위젯 통신 하나 뻗었는데, 메인 게시글과 헤더 전체 트리까지 전부 새하얗게 날아가면서 저 에러 방벽 텍스트만 덜렁 떠버리게 됐지.

✅ 영호의 국지적 방벽 설계 (파편 쪼개기 + Suspense 조합)

export default function CommunityPage() {
  return (
    <article className="layout_grid">
      <MainHeader />
 
      {/* ⚠️ 메인 게시판: 매우 중요!! 여기서 오류가 발생하면 전체 error.tsx 가 잡도록 냅둔다 */}
      <MainPostList />
 
      {/* 🛡️ 덜 중요한 사이드바 위젯:
          여기는 오류가 나도 사이트 이용에 무관하므로 별도의 도메인 폴더로 빼서 개별 error.tsx 관할권으로 두거나,
          수동 <ErrorBoundary> 라이브러리 구역으로 묶고 fallback UI를 조용히 띄워 메인 화면을 살린다! */}
      <aside>
        <SidebarRankingWidget />
      </aside>
 
    </article>
  )
}

🎯 한 걸음 더: 컴포넌트 단위의 정밀 타격 에러 처리

영철이는 궁금해졌어. "영호 리드 님, 그럼 error.tsx 파일 없이는 특정 컴포넌트 하나만 딱! 잡아서 격리할 순 없나요? 폴더를 매번 새로 만들긴 좀 번거로워서요."

영호 리드 님이 웃으며 대답했지. "당연히 있죠! error.tsx는 라우트 단위의 큰 격벽이라면, 우리가 직접 ErrorBoundary 컴포넌트로 감싸면 개별 컴포넌트 단위로 정밀 타격 방어가 가능해요."

1) react-error-boundary 활용 (권장)

가장 우아한 방법은 검증된 라이브러리를 쓰는 거야. 특정 컴포넌트가 오류가 나도 페이지 전체가 하얗게 변하는 걸 막아주지.

'use client'
 
import { ErrorBoundary } from 'react-error-boundary'
 
function ErrorFallback({ error, resetErrorBoundary }: any) {
  return (
    <div className="p-2 border border-red-200 bg-red-50 text-xs text-red-600">
      <p>위젯 로드 실패 😭</p>
      <button onClick={resetErrorBoundary} className="underline">다시 시도</button>
    </div>
  )
}
 
export default function Sidebar() {
  return (
    <aside>
      <h3>실시간 랭킹</h3>
      {/* 🛡️ 이 위젯 하나가 오류가 나도 사이드바 전체와 메인 페이지는 무사해! */}
      <ErrorBoundary
        FallbackComponent={ErrorFallback}
        onReset={() => {
          // 다시 시도할 때 수행할 로직
        }}
      >
        <SidebarRankingWidget />
      </ErrorBoundary>
    </aside>
  )
}

이렇게 하면 error.tsx가 담당하는 '페이지 전체' 혹은 '폴더 전체' 단위의 거시적 방어와, 컴포넌트 단위의 미시적 방어를 조화롭게 섞어서 "절대 사라지지 않는 앱" 을 만들 수 있어! 🐣
핵심 멘탈 모델: 에러 경계(error.tsx)을 어디 계층(폴더 레벨)에 둘 것인가?
에러가 난 곳에 error.tsx가 없다면? 에러 대상과 에러는 자기를 처리할 가장 가까운 상위 폴더의 error.tsx를 만날 때까지 부모 방향으로 전파(Bubble Up) 된다.
따라서, 살려야 하는 핵심 기둥(Layout)의 내부에 방벽을 오밀조밀하게 깔아주는 것이 파편화 설계의 꽃이다!

🚨 서버 다운 최후의 보루: global-error.tsx 🔴

질문 하나 해보자.
"만약에 제일 바깥 껍데기 기둥인 app/layout.tsx (html, body 태그가 선언된 그곳!) 자체에서 코드 짜다가 에러가 오류가 발생하면 어떡해? 제일 높은 곳이니까 걔를 감싸주는 부모(상위) error.tsx가 세상에 존재하지 않을 텐데?!"

정답이야. app/error.tsx 조차도 루트 layout.tsx의 에러를 방어해내지 못해. (오직 layout 내부의 페이지들만 방어함).
가장 무거운 신, 가장 최상위 layout.tsx에서 오류가 발생한 절체절명의 에러를 담아내는, 말 그대로 진짜 숨겨진 마지막 블랙박스가 예약어로 존재해.

// app/global-error.tsx (최상단 루트 구역에만 생성 가능)
'use client'
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // ⚠️ 여긴 layout이 터졌을 때 대체되는 곳이니까
    // 나 스스로가 반드시 <html> <body> 껍데기를 만들어내야만 해!!
    <html>
      <body>
        <h1>시스템 코어 붕괴 (Global Error 발동)</h1>
        <p>전면 장애 조치 중입니다... {error.message}</p>
        <button onClick={() => reset()}>재부팅 시도</button>
      </body>
    </html>
  )
}

💡 팁: global-error.tsx는 프로덕션 빌드에서만 활성화돼. (개발자 환경 개발 환경에서는 터미널 팝업이 우선될 수 있음). 오직 프로덕션 환경의 마지막 경계에서 최상위 서버 컴포넌트(layout.tsx)가 디비 통신 등에서 중단되어나갈 때만 튀어나오는 최후 방어선 역할을 수행하지.

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ Error Components must be Client Components...

원인: error.tsx 나 global-error.tsx 파일 최상단에서 'use client' 선언을 까먹었음.
해결책: 1초 만에 최상단에 'use client' 써주기. (런타임 에러 렌더링에 필수)

❌ 루트 layout.tsx가 터졌는데 app/error.tsx가 작동 안 하고 하얀 중단 화면 뜹니다!

원인: app/error.tsx 구조상 자신이 속한 layout.tsx 형제 파일의 에러는 막지 못함 (오염 법칙).
해결책: 루트 app/ 레벨 깊이에서는 layout.tsx를 감싸 방어할 수 있는 global-error.tsx 파일을 별도로 만들어야 완벽히 차단됨.

🏁 이번에 배운 내용 총정리

💡 한 줄로 기억하기
에러는 물과 같아서 방수문(error.tsx)이 없는 윗방(부모 컴포넌트)을 향해 꿀럭꿀럭 차오른다.
중요한 국지 컴포넌트 트리에는 촘촘하게 쉴드 파일을 폴더 단위로 심어놔야, 사이트 전체가 중단되는 오류 화면(YOD: Yellow Screen of Death)을 면할 수 있다!

📝 마무리 퀴즈

Q1. error.tsx가 클라이언트 컴포넌트여야 하는 이유는?

✅ 정답: reset 같은 복구 인터랙션을 제공해야 하기 때문이다.

💡 상세 해설: 에러 화면은 단순 안내문이 아니라 사용자가 다시 시도할 수 있는 경계다. 그래서 error.tsx는 use client가 필요한 특별 파일이다.

Q2. not-found.tsx와 error.tsx를 구분해야 하는 이유는?

✅ 정답: 존재하지 않는 리소스와 예외로 실패한 상황은 사용자 안내와 상태 코드가 다르기 때문이다.

💡 상세 해설: 삭제된 게시글은 404 경험으로, DB 장애는 복구 가능한 에러 화면으로 다루는 편이 자연스럽다. 둘을 섞으면 사용자와 검색 엔진 모두에게 모호해진다.

Q3. 영철이의 테스트 타임: 게시글 상세 조회에서 권한은 있지만 글 ID가 없다. 어떤 흐름이 맞을까?

✅ 정답: notFound()를 호출해 해당 세그먼트의 not-found UI로 보낸다.

💡 상세 해설: 예외를 던져 error.tsx로 보내면 "문제가 생겼다"는 메시지가 된다. 실제로는 리소스가 없는 것이므로 404 경계를 쓰는 게 더 정확하다.

🐣 영철이의 퇴근 일기

오늘은 에러 처리를 catch 한 줄이 아니라 사용자 여정의 일부로 보게 됐다.

💡 "에러 경계는 실패를 숨기는 장치가 아니라 회복 가능한 범위를 정하는 장치다."

다음에는 실패 종류를 먼저 이름 붙이고, 그에 맞는 경계 파일을 고르겠다.

🔗 더 알아보기

• Next.js Docs: Error Handling

🔗 더 알아보기

• Next.js Docs: Error Handling