[사람별] Next.js 에러 핸들링 (error.tsx)

문제 상황

Next.js를 사용해 캘린더 페이지를 개발하는 중,
Supabase 통신 중 발생하는 에러를 페이지 라우터 세그먼트 내의 error.tsx로 통합해서 처리하려 했다.

하지만 에러를 던질 때 내가 지정한 메시지와 런타임 중 발생하는 시스템 메시지가 섞여 나오는 문제가 있었다.

또한,

 

• app/api/**/route.ts (라우트 핸들러)
• supabase 호출 함수(fetch)
• 클라이언트 컴포넌트 (page.tsx)
• 탠스택 쿼리(useQuery)

이렇게 여러 레이어를 거치면서 에러 흐름을 깔끔하게 잡는 것도 고민이 필요했다.

 

최종적인 에러 흐름은 아래와 같다.

• 라우트 핸들러

성공or에러를 객체 형태로 받아서 return 👉🏻 페이지에서 에러 객체를 잡아서 throw 👉🏻 error.tsx 잡음

 

import ENV from '@/constants/env.constant';
import { NextResponse } from 'next/server';

// 공휴일 라우트 핸들러
export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const year = searchParams.get('year') || new Date().getFullYear().toString();

  try {
    const url = `${ENV.HOLIDAY_URL}/getRestDeInfo?ServiceKey=${ENV.HOLIDAY_KEY}&solYear=${year}&_type=json&numOfRows=100`;
    const res = await fetch(url);

    if (!res.ok) {
      throw new Error(`공휴일 API 응답 오류: ${res.statusText}`);
    }

    const data = await res.json();
    // 데이터 구조 검증
    if (!data.response || !data.response.body) {
      console.error('유효하지 않은 API 응답 형식:', data);
      return NextResponse.json({ error: '공휴일 데이터 형식이 올바르지 않습니다' }, { status: 500 });
    }
    return NextResponse.json(data); //정상 응답 반환
  } catch (error) {
    console.error('공휴일 데이터 호출 중 오류 발생:', error);
    return NextResponse.json({ error: '공휴일을 불러올 수 없습니다' }, { status: 500 });
  }
}

• supabase 통신

각 통신 함수에서 console.error & throw new Error 👉🏻 페이지 내의 쿼리 훅에서 error 꺼내기  👉🏻 각 에러 처리 후 throw 👉🏻 error.tsx 잡음

1. plans 데이터 불러오기
export const getPlans = async (planId: string): Promise<PlansType> => {
  const { data, error } = await supabase.from(PLANS).select('*').eq('plan_id', planId).single();

  if (error) {
    console.error('약속을 불러오는 중 오류가 발생했습니다:', error);
    throw new Error('약속을 불러오는 중 문제가 발생했습니다. 다시 시도해주세요.');
  }

  return data;
};

2. 쿼리 훅에서 error 꺼내기
  const { data: holidays, error: holidaysError } = useGetHolidays(String(calendarYear)); //공휴일
  const { data: events, isPending, error: plansError } = useGetCalendarPlans(user, calendarYear, moment); //약속(readonly)
  const {
    data: selectedPlanData,
    error: selectPlanError,
    refetch: refetchSelectedPlan,
  } = useGetSelectPlan(selectedPlanId ?? '');
    const { mutate: updateEvent, error: updatePlanError } = useUpadateEventMutate();
    
    
3. 에러 모아서 throw
  if (holidaysError || plansError || selectPlanError || updatePlanError) {
    const error = new Error('캘린더 데이터를 불러오는 중 문제가 발생했습니다.') as Error & {
      originalError?: Error | null;
    };
    error.originalError = holidaysError ?? plansError ?? selectPlanError ?? updatePlanError;
    throw error;
  }

에러 흐름 전체 구조

에러 처리를 다음과 같은 규칙으로 정리했다.

 

1. 라우트 핸들러(app/api//route.ts)**

 

서버 사이드에서 에러 발생 시 → NextResponse.json({ error }, { status }) 로 클라이언트에 에러 전달

return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });

 

 

 

2. 통신 로직 (Supabase 호출 함수 등)

 

fetch 함수에서는 통신 실패 시 throw new Error('커스텀 메시지') 로 에러 던지기

🔥 이때 통신 자체가 안 된다면 런타임 에러가 발생할 수 있으니 주의.

if (error) {
  throw new Error('약속을 불러오는 중 오류가 발생했습니다.');
}

 

 

 

3. 페이지 컴포넌트 (ex. app/(routes)/calendar/page.tsx)

 

직접적인 오류 발생 시 throw new Error('메시지') → error.tsx로 연결되도록 설정

if (!data) {
  throw new Error('데이터를 불러올 수 없습니다.');
}

 

 

 

4. 탠스택 쿼리 (useQuery, useMutation)

 

쿼리 훅 내부에서는 Next.js의 error.tsx를 직접 건드리지 않고
error, isError 플래그를 통해 클라이언트 컴포넌트 안에서 에러 처리

const { data, error, isError } = useGetCalendarPlans();

if (isError) {
  throw error;
}

 

 

 

✅ 흐름 정리

 

• 라우트 핸들러에서 발생하는 에러는 json 응답으로 내려옴
• 통신(fetcher) 단에서 받은 에러는 throw new Error로 명시적으로 던짐
• 페이지 컴포넌트에서는 통합적으로 에러를 받아 필요한 경우 다시 throw
• 최종적으로 error.tsx가 모든 에러를 받아 처리하는 구조

 

 

 

error.tsx

error.tsx에서는 이렇게 메인 에러와 서브 에러(originalError)를 나누어 출력했다.

• 메인 에러: 캘린더 페이지에서 throw한 메세지 '캘린더 데이터를 불러오는 중 문제가 발생했습니다.'
• 서브 에러: supabase 통신 로직에서 throw한 디테일 메세지 '약속을 불러오는 중 오류가 발생했습니다. 다시 시도해주세요'

에러를 콘솔에도 출력해서 디버깅하기 쉽게 설정했다.

'use client';

import GenericError from '@/components/Error';

export default function ErrorPage({ error, reset }: { error: Error & { originalError?: Error }; reset: () => void }) {
  console.error('메인 에러:', error);

  if (error.originalError) {
    console.error('원래 에러:', error.originalError);
  }

  return (
    <GenericError
      error={error}
      originalError={error.originalError ?? null}
      refetch={reset} // reset 함수는 Next.js가 제공하는 재시도 함수
    />
  );
}

 

 

 

GenericError 컴포넌트

렌더링 시, error.message와 originalError.message 를 각각 보여줄 수 있도록 했다.

import { Warning } from '@phosphor-icons/react';

type GenericErrorProps = {
  error?: Error | null;
  originalError: Error | null;
  refetch?: () => void;
};

export default function GenericError({ error, refetch, originalError }: GenericErrorProps) {
  return (
    <div className='flex min-h-screen flex-col items-center justify-center gap-8'>
      <Warning size={60} className='text-secondary-600' />
      <h2 className='title text-[45px] font-bold text-primary-700'>Error!</h2>
      {error?.message && originalError?.message && (
        <section className='flex flex-col items-center text-[23px] text-primary-500'>
          <p>{error?.message}</p>
          <p>Detail: {originalError?.message}</p>
        </section>
      )}
      {refetch && (
        <button
          onClick={refetch}
          className='rounded-md border-2 bg-primary-500 p-4 font-bold text-white hover:bg-primary-600'
        >
          다시 시도
        </button>
      )}
    </div>
  );
}

 

 

일부러 통신 에러를 만드는 방법

 

Supabase 요청 중 발생하는 에러는 잘 잡히지만,
코드 자체에서 런타임 에러가 나면 Supabase에 도달조차 못 하고 죽는다.

예를 들면 아래와 같이 Supabase 요청을 보내기도 전에 런타임 에러가 발생한다.
(따라서 originalError가 존재하지 않는다.)

const { error } = await supabase.from(PLAS).select('*'); // PLAS가 undefined

 

 

따라서 Supabase 통신 실패를 일부러 만들고 싶으면

• 잘못된 테이블명 사용
• 필수 컬럼을 누락
• 존재하지 않는 필드를 쿼리

등을 통해 에러를 발생시키고,
정상적으로 응답이 오게 한 뒤 거기서 error 체크 후 던지는 식으로 처리해야 한다.

 

 

최종 결과 및 느낀점

 

이번 작업을 통해 런타임 에러와 통신 에러를 명확히 구분해서 다뤄야 한다는 걸 다시 깨달았다.

또한 throw new Error를 쓰는 위치, 에러를 받는 위치(error.tsx), 표시하는 방법(GenericError 컴포넌트)까지 모두 설계해야
에러 핸들링이 완성된다는 것을 경험했다.