🚀 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. 영철이가 쇼핑몰 결제 페이지 폴더를 세팅 중이다. app/purchase/ 폴더 내부에 layout.tsx, page.tsx, error.tsx 파일 세 개가 있다. 어느 날 page.tsx에서 서버 액션을 처리하다 throw new Error("결제 승인 거부") 가 터졌다. 이때, 화면 전체 렌더링 측면에서 보았을 때 purchase/layout.tsx 단에서 그려주던 GNB(글로벌 상단 네비게이션)와 사이드 카트 바는 유저 화면에 살아있을까? 날아가서 안 보일까?

✅ 정답: 완벽하게 살아있다 (유지된다).

💡 상세 해설: 같은 폴더 구역에 있는 방어벽 error.tsx는, 오직 자식 컴포넌트들(통상 page.tsx)이 발생시킨 에러 범위까지만을 격리하고 그 구역만 Fallback UI (에러 메시지)로 덮어버린다. 형제 파일인 layout.tsx는 page.tsx를 품고 있는 거대한 껍데기(부모 개념 트리)이므로, 에러의 충돌 여파(error.tsx 방벽 바깥)를 전혀 받지 않고 튼튼하게 화면에 남아 GNB 역할을 무사히 수행한다. 이것이 폴더 기반 방어 아키텍처의 강력함이다.

Q2. 방어벽인 error.tsx 파일 안에서 버튼을 클릭하면 에러가 났던 원래 컴포넌트를 강제로 뻗게 만든 원인을 뒤엎고 처음부터 다시 fetch 해보라고 서버에 재요청(강제 회복 리프레시)을 보내는 역할을 하는 핵심 Props 파라미터 함수 이름은 무엇인가?

✅ 정답: reset() 함수이다.

💡 상세 해설: error.tsx 컴포넌트는 Next.js로부터 무조건 두 개의 프롭스 패키지를 쥐고 태어난다. 하나는 에러 덤프 덩어리인 error 상자, 다른 하나는 죽은 섹션을 다시 마운트시켜 렌더링 서버와 다시 통신을 강행케 하는 reset 액션 함수이다. onClick={() => reset()} 코드는 SPA 세상에서 새로고침 없이 해당 부분 컴포넌트만 회복 마법을 발동시키는 고급 치유기(Heal)이다.

🐣 영철이의 퇴근 일기

오늘은 정말 십년감수했어. API 하나 터졌다고 사이트 전체가 뻗어버리는 걸 보면서 프론트엔드 세계의 무서움을 느꼈거든. 하지만 영호 리드 님이 가르쳐주신 '방화 셔터(error.tsx)' 와 더 세밀한 '개별 격벽(ErrorBoundary)' 의 위력을 확인하고 나니 이제는 어떤 에러가 터져도 당황하지 않을 것 같아!

💡 오늘의 교훈: "에러는 물과 같아서 방수문(error.tsx) 이 없으면 윗방으로 역류한다. 라우트 단위의 큰 셔터뿐만 아니라, 컴포넌트 단위의 정밀한 격벽(ErrorBoundary) 도 적재적소에 배치해 앱의 생존력을 극대화하자!"

단순히 try-catch 로 에러를 숨기는 게 아니라, 에러가 발생한 지점을 명확하게 격리하고 사용자에게 다시 시도할 기회(reset) 까지 주는 설계가 얼마나 세련된 방식인지 깨달았어. 오늘 긴장했더니 어깨가 뻐근하네. 운동 가서 스트레칭 좀 하고 푹 쉬어야지! 내일은 에러 없는 무결점 코드를 짜는 '디버깅 마스터' 가 되고 말 거야. 🐣

🔗 더 알아보기

• Next.js Docs: Error Handling