Next.js - (10) error 페이지로 에러 상태 처리하기

 

 

 

이번 포스트에서는 비동기 데이터를 가져오는 중 오류가 발생했을 때, 사용자에게 에러 페이지를 보여주는 방법에 대해 알아보겠습니다.

 

 

✅ 기본 개념

Next.js에서는 error.js라는 파일을 사용하여 각 라우트별 에러 UI를 정의할 수 있습니다.
이 파일은 해당 라우트에서 에러가 발생했을 때 자동으로 렌더링되며, loading.js와 마찬가지로 페이지 폴더 안에 위치해야 합니다.

 

 

 

✅ 사용 예시

// app/meals/error.js

"use client"; // 반드시 클라이언트 컴포넌트여야 합니다!

export default function Error({ error }) {
  return (
    <main className="error">
      <h1>An error occurred!</h1>
      <p>{error.message}</p>
    </main>
  );
}

 

 

✅ 주요 포인트 정리

• error.js는 반드시 클라이언트 컴포넌트여야 하므로 "use client" 지시문을 파일 상단에 작성해야 합니다.
• 함수의 인자로 error 객체가 전달되며, 해당 객체의 메시지를 통해 에러 내용을 표시할 수 있습니다.
• 파일 위치는 loading.js와 동일하게, 에러 처리를 원하는 라우트 폴더 안에 위치해야 합니다.
  • 예: /app/meals/error.js → /meals 경로에서 에러 발생 시 표시됨

---

✅ 동작 방식

error.js는 다음과 같은 상황에서 자동으로 호출됩니다:

• async 함수에서 throw new Error()를 호출한 경우
• 서버/클라이언트 컴포넌트 내 비동기 처리 중 오류가 발생한 경우
• Suspense로 감싼 컴포넌트 내부에서 비동기 오류가 발생한 경우

---

✅ 예시 흐름

1. getMeals() 함수에서 네트워크 요청 중 문제가 발생
2. MealsPage 또는 Meals 컴포넌트 내부에서 throw
3. Next.js가 /meals/error.js를 찾아 렌더링
4. 사용자에게 커스텀 에러 메시지 표시

 

🔍  React의 Error Boundary는 클라이언트에서만 동작

Next.js의 error.js는 React의 Error Boundary 기능을 기반으로 동작합니다. 그런데 이 기능은 다음과 같은 특징을 가집니다:

• Error Boundary는 오직 클라이언트 렌더링에서만 동작합니다.
• 서버 컴포넌트에서는 에러가 발생하면 React가 전체 컴포넌트를 렌더링하지 않고 곧바로 실패 처리합니다.
• 따라서 에러 처리를 위해 사용하는 error.js는 반드시 클라이언트 컴포넌트여야만 정상 작동합니다.

 

 

 

 

 

 

 

📝 마무리

Next.js의 error.js는 라우트 단위로 에러 처리를 할 수 있게 해주며, 사용자에게 더 친절한 피드백을 제공할 수 있는 좋은 수단입니다.

다음 포스트에서는 not-found.js를 통해 404 페이지를 처리하는 방법도 함께 알아보겠습니다!