🛡️ Next.js App Router 에러 처리 완전 가이드

Next.js App Router는 페이지 단위, 전역 단위의 다양한 에러 처리를 공식적으로 지원합니다.
예상된 오류(404 등)뿐만 아니라 예기치 못한 런타임 오류까지 다룰 수 있도록 구조화된 방식으로 제공됩니다. 이 글에서는 그 핵심인 not-found.tsx, error.tsx, global-error.tsx 파일의 역할과 사용법을 실전 예제와 함께 정리합니다.

✅ 1. not-found.tsx – 404 에러 처리

리소스를 찾을 수 없는 상황(예: 게시글이 존재하지 않을 때)에는 notFound() 함수를 호출하여 404 페이지로 유도할 수 있습니다.

사용 예시

// app/posts/[id]/page.tsx
import { notFound } from 'next/navigation';

export default async function Page({ params }) {
  const post = await getPostById(params.id);
  if (!post) notFound();

  return <div>{post.title}</div>;
}

커스텀 404 페이지 작성

// app/posts/[id]/not-found.tsx
export default function NotFound() {
  return <h1>이 게시글을 찾을 수 없습니다.</h1>;
}

전체 앱에 공통적으로 적용하고 싶다면 app/not-found.tsx를 사용하면 됩니다.

💥 2. error.tsx – 페이지 단위 예외 처리

예기치 못한 에러(예: fetch 실패, 렌더링 중 오류 등)는 해당 라우트 폴더에 error.tsx를 추가하여 처리합니다.

기본 구조

// app/dashboard/error.tsx
'use client';

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h2>에러가 발생했습니다.</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>다시 시도</button>
    </div>
  );
}

error: 발생한 에러 객체
reset(): 에러 상태를 초기화하고 컴포넌트를 재렌더링

반드시 'use client'가 선언되어야 합니다.

🌐 3. global-error.tsx – 전역 에러 처리

루트 레이아웃에서 발생한 에러(초기 렌더링 중 에러 등)는 global-error.tsx를 통해 처리할 수 있습니다.

사용 예시

// app/global-error.tsx
'use client';

export default function GlobalError({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <html>
      <body>
        <h1>앱에 오류가 발생했습니다.</h1>
        <p>{error.message}</p>
        <button onClick={() => reset()}>홈으로</button>
      </body>
    </html>
  );
}

루트에 있어야 하며, <html>과 <body> 태그를 포함해야 합니다.
페이지 전환 시 자동 복구되지 않으므로 수동 reset() 필요

🔁 에러 복구 흐름

error.tsx 또는 global-error.tsx에서 reset() 함수를 호출하면 해당 컴포넌트는 다시 요청되며 초기 상태로 돌아갑니다.

<button onClick={() => reset()}>다시 시도</button>

API 서버 일시적 다운, DB 연결 실패 등 일시적 오류 복구에 효과적
새로고침 없이 사용자에게 빠른 리트라이 기능 제공

📁 실전 구조 예시

app/
├── layout.tsx
├── global-error.tsx        ← 전역 예외 처리
├── not-found.tsx           ← 전체 404 처리
└── dashboard/
    ├── page.tsx
    ├── error.tsx           ← dashboard 전용 예외 처리
    └── not-found.tsx       ← dashboard 전용 404 처리

✅ 요약

항목 역할 위치

notFound()	404 유도 함수	서버 컴포넌트 내부
not-found.tsx	404 페이지	폴더 또는 루트
error.tsx	라우트 단위 에러 경계	페이지 폴더 내
global-error.tsx	전역 에러 경계 (레이아웃 수준)	app/ 루트
reset()	에러 상태 초기화 및 재렌더링	error 컴포넌트 내부

Next.js, App Router, 에러 핸들링, 에러 경계, not-found.tsx, error.tsx, global-error.tsx, reset 함수, 예외 처리, 사용자 경험, SEO 최적화 10개