본문으로 건너뛰기
fe.run

에러 바운더리가 쿼리를 못 잡을 때

글 복사 완료!

Error Boundary 를 달았는데 쿼리 에러가 안 잡히던 그 순간을 풀어요.

·24분·

<ErrorBoundary> 로 컴포넌트를 감쌌는데 fetch 가 실패해도 fallback 화면이 안 뜬 적 있죠. 저도 처음엔 바운더리가 고장 난 줄 알았어요. TanStack Query 의 에러는 기본적으로 isError 상태로만 남거든요. 그래서 throwOnError 로 에러를 렌더 단계에 다시 던져야 React 의 Error Boundary 가 잡고, QueryErrorResetBoundary 의 reset 을 onReset 에 묶어야 재시도까지 이어져요.

Error Boundary 가 못 잡는 자리

Error Boundary 는 자식 컴포넌트가 렌더되는 도중 던진 에러를 잡아서 fallback UI 로 바꿔주는 장치예요. React 공식 문서가 정해둔 범위가 꽤 좁아요. 렌더 바깥에서 나는 에러는 못 잡거든요.

"Error boundaries do not catch errors for event handlers, asynchronous code, server side rendering, errors thrown in the error boundary itself." - React

이벤트 핸들러 안에서 난 에러, setTimeout 같은 비동기 콜백에서 난 에러는 바운더리 바깥이에요. 데이터 페칭은 본질적으로 비동기라서, 응답이 실패해도 그 에러는 렌더 흐름을 타고 올라오지 않아요.

여기서 첫 번째 오해가 생겨요. TanStack Query 로 데이터를 받을 때 queryFn 이 reject 하면, 라이브러리는 그 에러를 삼켜서 error 라는 상태값으로 바꿔둬요. 컴포넌트는 멀쩡히 렌더되고, isError 가 true 인 채로 돌아가죠. 던져진 에러가 없으니 위에 있는 Error Boundary 는 아무 일도 없었던 것처럼 가만히 있어요. 바운더리가 고장 난 게 아니라, 애초에 잡을 에러가 안 올라온 거예요.

그래서 함수 컴포넌트로는 Error Boundary 를 못 만든다는 점도 같이 알아두면 좋아요. getDerivedStateFromError 가 필요해서 클래스로 써야 하거든요. React 팀은 직접 클래스를 쓰는 대신 react-error-boundary 패키지를 권합니다. 아래 예시도 이 패키지를 기준으로 할게요.

throwOnError 로 에러를 렌더 단계로 올리기

쿼리 에러를 바운더리가 잡게 하려면, 삼켜둔 에러를 렌더 단계에서 다시 던지라고 알려줘야 해요. 그 스위치가 throwOnError 예요. 예전 버전에서 useErrorBoundary 라고 부르던 옵션인데, v5 에서 이름이 바뀌었어요.

import { useQuery } from "@tanstack/react-query";
 
function Profile() {
  const { data } = useQuery({
    queryKey: ["profile"],
    queryFn: fetchProfile,
    throwOnError: true,
  });
 
  return <h1>{data.name}</h1>;
}

throwOnError: true 로 두면 쿼리가 실패할 때 그 에러가 render phase 에서 throw 돼요. 렌더 도중 던진 에러니까, 이제 가장 가까운 Error Boundary 가 정상적으로 잡아요. isError 분기를 컴포넌트마다 손으로 쓰는 대신, 에러 처리를 한 군데 바운더리로 모으는 거죠.

throwOnError 에는 함수도 줄 수 있어요. (error) => error.response?.status >= 500 처럼 두면 서버 에러만 바운더리로 올리고, 400 대 같은 건 컴포넌트 안에서 직접 다루게 갈라낼 수 있고요.

Suspense 모드의 조용한 함정

useSuspenseQuery 를 쓰면 throwOnError 를 켜지 않아도 에러가 자동으로 던져져요. 로딩은 Suspense 가, 에러는 Error Boundary 가 맡는 구조라서요. 이 갈라짐이 어떻게 돌아가는지는 Suspense 안쪽과 useSuspenseQuery 에서 따로 풀어뒀어요.

근데 여기에 놓치기 쉬운 단서가 하나 있어요. suspense 모드는 에러를 항상 던지는 게 아니에요.

"Not all errors are thrown to the nearest Error Boundary per default, we're only throwing errors if there is no other data to show." - TanStack Query

보여줄 데이터가 하나도 없을 때만 에러를 던진다는 뜻이에요. 한 번이라도 성공해서 캐시에 값이 남아 있으면, 재요청이 실패해도 에러를 안 올리고 그 stale 데이터를 그대로 화면에 둬요.

이게 "바운더리를 분명히 달았는데 왜 에러 화면이 안 뜨지" 의 진짜 범인일 때가 많아요. 처음 마운트될 때는 캐시가 비어 있으니 에러가 정상적으로 올라가요. 근데 사용자가 한 번 데이터를 본 뒤 다시 들어와서 실패하면, 라이브러리는 빈 화면을 보여주느니 옛날 데이터라도 보여주는 쪽을 골라요. 의도된 동작이지만, 모르고 보면 바운더리가 새는 것처럼 느껴지죠.

QueryErrorResetBoundary 로 재시도까지 잇기

에러를 바운더리로 올렸으면, 이제 "다시 시도" 버튼을 눌렀을 때 쿼리가 재실행되게 묶어야 해요. 여기서 두 개의 reset 이 만나요. react-error-boundary 의 resetErrorBoundary 는 바운더리의 에러 상태를 비우고 렌더를 다시 시도해요. TanStack 의 reset 은 쿼리에게 "이제 다시 시도해도 된다" 고 알리는 신호고요. 둘을 안 묶으면, 화면은 멀쩡한 컴포넌트로 돌아가지만 쿼리는 여전히 에러 상태라 또 바로 fallback 으로 떨어져요.

QueryErrorResetBoundary 가 그 둘을 잇는 자리예요. render prop 으로 reset 함수를 내려주는데, 이걸 바운더리의 onReset 에 연결하면 돼요.

import { QueryErrorResetBoundary } from "@tanstack/react-query";
import { ErrorBoundary } from "react-error-boundary";
 
function Page() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ resetErrorBoundary }) => (
            <div>
              <p>데이터를 못 불러왔어요.</p>
              <button onClick={() => resetErrorBoundary()}>다시 시도</button>
            </div>
          )}
        >
          <Profile />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

버튼을 누르면 일이 줄줄이 일어나요. 그 인과 사슬을 그림으로 보면 이래요.

다시 시도 버튼 한 번이 만드는 reset 인과 사슬

resetErrorBoundary 호출이 onReset 을 트리거하고, 거기 묶인 reset 이 쿼리에게 다시 시도해도 된다고 허락해요. 그 뒤 React 가 실패했던 렌더를 다시 그리고, 이번엔 쿼리가 새로 실행돼요. 컴포넌트 대신 useQueryErrorResetBoundary 훅을 써도 같은 일을 해요. const { reset } = useQueryErrorResetBoundary() 로 꺼내서 똑같이 onReset 에 꽂으면 되거든요. 컴포넌트 버전이 부담스럽고 한 군데서만 reset 이 필요하면 훅 쪽이 가벼워요.

말로만 보면 헷갈리니까, 이 흐름을 바닐라 React 로 줄여서 직접 눌러볼 수 있게 해뒀어요. 처음엔 렌더에서 에러를 던지고, 다시 시도를 누르면 바운더리가 에러를 비우고 다시 그려서 성공해요. 실제 QueryErrorResetBoundary 가 하는 일과 같은 모양이에요.

getDerivedStateFromError 가 에러를 잡아 fallback 으로 바꾸고, 다시 시도가 그 에러를 비우면서 부모의 상태를 한 칸 올려요. 다음 렌더에서 FlakyData 가 성공하는 게 곧 쿼리 재실행에 해당하고요.

resetErrorBoundary 만 부르면 생기는 일

처음 이 조합을 붙일 때 저는 onReset 을 빼먹었어요. 다시 시도를 눌러도 fallback 이 깜빡이지도 않고 그대로였고, 네트워크 탭엔 요청이 한 줄도 안 찍혔어요. 버튼이 고장 난 줄 알았는데, 바운더리는 제 할 일을 다 했더라고요. 문제는 쿼리 쪽에 남아 있었어요.

단서는 에러가 어디에 저장되느냐예요. fallback 이 떠 있는 동안 Profile 은 언마운트되지만, 쿼리의 상태는 컴포넌트가 아니라 QueryClient 의 캐시에 살아요. 그래서 resetErrorBoundary 가 children 을 다시 마운트해도, 새로 뜬 useQuery 는 status: 'error' 로 남아 있는 같은 쿼리를 다시 읽어요.

원래라면 여기서 재요청이 나가야 해요. retryOnMount 옵션의 기본값이 true 라서, 에러 상태인 쿼리가 마운트되면 다시 시도하거든요. 근데 throwOnError 나 suspense 를 켜면 사정이 달라져요. useQuery 는 렌더할 때마다 아래 함수를 먼저 거치거든요.

// packages/react-query/src/errorBoundaryUtils.ts (요약)
export const ensurePreventErrorBoundaryRetry = (options, errorResetBoundary, query) => {
  const throwOnError = /* 쿼리에 이미 에러가 있으면 (error, query) 로 해석한 값 */;
 
  if (options.suspense || throwOnError) {
    // Prevent retrying failed query if the error boundary has not been reset yet
    if (!errorResetBoundary.isReset()) {
      options.retryOnMount = false;
    }
  }
};

바운더리가 리셋됐다는 표시(isReset())가 없으면 이번 렌더의 옵션에서 retryOnMount 를 꺼버려요. 재시도 시점을 쿼리가 알아서 정하지 않고, 바운더리 리셋 신호에 맡기는 구조예요.

"Prevent retrying failed query if the error boundary has not been reset yet" - TanStack Query 소스 주석

바운더리가 아직 리셋되지 않았다면, 실패한 쿼리를 다시 시도하지 말라는 거예요. 여기서 말하는 리셋은 react-error-boundary 의 리셋이 아니라 TanStack 쪽 reset() 이에요.

꺼진 retryOnMount 는 마운트할 때 fetch 를 할지 정하는 판정에서 바로 걸려요.

// packages/query-core/src/queryObserver.ts (요약)
function shouldLoadOnMount(query, options) {
  return (
    options.enabled !== false &&
    query.state.data === undefined &&
    !(query.state.status === "error" && options.retryOnMount === false)
  );
}

데이터가 없고, 상태가 error 이고, retryOnMount 가 false 면 마운트해도 불러오지 않아요. 이 조각들을 이어 붙이면 다시 시도 버튼 한 번에 일어나는 일이 이래요.

1

fallback 이 떠 있는 동안

Profile 은 언마운트됐지만 쿼리 캐시에는 status 'error', data undefined 인 쿼리가 그대로 남아 있어요.

2

resetErrorBoundary 호출

onReset 에 아무것도 안 묶여 있으니 바운더리는 자기 에러 상태만 비우고 children 을 다시 마운트해요.

3

retryOnMount 가 꺼짐

isReset() 이 false 라서 ensurePreventErrorBoundaryRetry 가 이번 렌더의 retryOnMount 를 false 로 바꿔요.

4

fetch 판정에서 탈락

shouldLoadOnMount 가 false 를 돌려줘요. 결과는 isError true, isFetching false 그대로예요.

5

렌더 안에서 다시 throw

구독도 fetch 도 하기 전에 useQuery 가 캐시에 있던 에러를 그대로 던져요. 요청은 0번, 화면은 곧장 fallback 으로 돌아가요.

reset 이 바꾸는 건 플래그 하나

그럼 reset() 은 뭘 하길래 이 사슬을 끊을까요. 까보면 싱거워요. QueryErrorResetBoundary 가 내려주는 값은 클로저 변수 하나거든요.

// packages/react-query/src/QueryErrorResetBoundary.tsx (요약)
function createValue() {
  let isReset = false;
  return {
    clearReset: () => {
      isReset = false;
    },
    reset: () => {
      isReset = true;
    },
    isReset: () => isReset,
  };
}

reset() 은 쿼리 캐시를 건드리지 않아요. 에러도 그대로 남아 있고, React state 도 아니라서 이것만 불러서는 리렌더도 안 일어나죠. 대신 react-error-boundary 는 onReset 을 먼저 부르고 나서 children 을 다시 마운트해요. 그래서 다음 렌더의 isReset() 이 true 가 되고, retryOnMount 도 꺼지지 않고요. shouldLoadOnMount 를 통과한 쿼리는 첫 렌더부터 에러 대신 pending, fetching 상태로 보이고, 요청이 나가요.

커밋이 끝나면 useQuery 안의 effect 가 clearReset() 으로 플래그를 다시 내려요. 재요청이 또 실패하면 다음 렌더에서는 retryOnMount 가 꺼지고 fallback 으로 돌아가요. 버튼 한 번에 재시도 한 번, 딱 그만큼만 허락하는 셈이죠.

이 흐름은 캐시에 data 가 없는 쿼리 얘기예요. 한 번 성공해서 data 가 남아 있는 쿼리는 shouldLoadOnMount 가 아니라 refetchOnMount 와 staleTime 이 재요청 여부를 정해요. suspense 모드라면 앞에서 본 것처럼 애초에 에러를 던지지 않고요.

에러를 초기화하는 방법들

다시 시도를 만드는 길은 reset 말고도 몇 개 더 있어요. 갈리는 기준은 두 가지예요. 리마운트된 쿼리가 fetch 판정을 통과하는지, 그리고 초기화가 어디까지 번지는지.

방법쿼리 상태리마운트 때 요청주의할 점
resetErrorBoundary 만error 그대로안 나감곧바로 fallback 으로 돌아와요
onReset={reset}error 그대로, 플래그만 켬나감경계 안의 쿼리 전체가 대상이에요
onReset 에서 resetQueries({ queryKey })초기 상태 (pending)나감키를 빼면 캐시 전체가 초기화돼요
onReset 에서 invalidateQueries / refetchQuerieserror 그대로안 나감구독자가 없어 refetch 대상에서 빠져요

useQueryErrorResetBoundary 훅은 가장 가까운 QueryErrorResetBoundary 의 값을 꺼내요. 감싼 경계가 없으면 모듈 전역에 하나 있는 기본값을 쓰고요. 그래서 경계 없이 훅만 써도 동작은 하지만, reset 이 앱 전체 쿼리에 걸려요. 페이지나 영역 단위로 가르고 싶으면 컴포넌트로 감싸는 게 맞아요.

resetQueries 가 되는 이유는 조금 우회적이에요. onReset 이 불리는 시점엔 children 이 언마운트돼 있어서 그 쿼리를 구독하는 컴포넌트가 없어요. 그러니 refetch 는 안 일어나고 상태만 생성 직후로 되돌아가요. 리마운트할 때 retryOnMount 는 여전히 꺼지지만, 막는 조건은 상태가 error 일 때만이라 pending 이 된 쿼리는 그냥 통과해요. 대신 부작용이 있어요. queryKey 를 빼먹으면 다른 화면의 캐시까지 전부 날아가고, initialData 가 있는 쿼리는 그 값으로 돌아가요.

invalidateQueries 와 refetchQueries 는 상태를 안 건드려요. 기본 refetch 대상은 구독 중인(active) 쿼리인데, fallback 이 떠 있는 동안 그 쿼리는 구독자가 없어서 대상에서 빠지고요. 결국 resetErrorBoundary 만 부른 것과 같은 길로 가요.

react-error-boundary 의 resetKeys 도 같은 판정을 받아요. 배열 값이 바뀌면 바운더리가 스스로 리셋하는데, 이때도 onReset 이 reason: "keys" 와 함께 불려요. 키가 쿼리 키까지 바꾸면 새 쿼리라 문제가 없어요. 근데 같은 데이터를 보여주는 탭의 경로처럼 쿼리 키와 상관없는 값이면, 리셋 뒤 다시 마운트된 컴포넌트가 에러 난 그 쿼리를 그대로 읽어요. onReset 에 reset 을 묶어두면 버튼이든 키 변경이든 같은 길을 타요.

import { QueryErrorResetBoundary } from "@tanstack/react-query";
import { ErrorBoundary } from "react-error-boundary";
 
function Section({ pathname, children }) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          resetKeys={[pathname]}
          onReset={reset}
          fallbackRender={({ resetErrorBoundary }) => (
            <button onClick={() => resetErrorBoundary()}>다시 시도</button>
          )}
        >
          {children}
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

기본은 이 모양이면 충분해요. resetQueries 는 캐시에 남은 값까지 버리고 처음부터 불러야 할 때만, 키를 좁혀서 쓰는 쪽을 권해요.

그래서 어디에

쿼리 에러가 Error Boundary 로 안 올라오는 건 바운더리 잘못이 아니라, 에러가 상태로 삼켜져서예요. throwOnError 로 다시 던지고, suspense 모드라면 캐시에 데이터가 남아 있을 때 에러가 조용히 묻힌다는 걸 기억하세요. 다시 시도가 안 먹히는 것도 뿌리가 같아요. 에러는 컴포넌트가 아니라 캐시에 남아 있고, 바운더리가 리셋됐다는 신호가 없으면 쿼리는 다시 마운트돼도 재요청하지 않거든요. 그래서 resetErrorBoundary 와 QueryErrorResetBoundary 의 reset 은 항상 한 쌍으로 onReset 에 묶어두면 돼요. 여러 쿼리를 한 화면에 펼칠 때 실패를 어떻게 가를지는 병렬인 줄 알았던 세 줄의 쿼리 에서 이어서 볼 수 있어요.

자주 묻는 질문

답을 펼치기 전에 스스로 답해보세요

로딩 상태도 바운더리 단위로 모으고 싶으면 useSuspenseQuery 가 자연스럽고, 기존 useQuery 코드에 에러 처리만 얹고 싶으면 throwOnError 옵션이 가벼워요. 둘 다 에러는 Error Boundary 로 올라가요.
둘 다 같은 reset 을 내려줘요. 다만 훅은 감싼 QueryErrorResetBoundary 가 없으면 앱 전역 값을 쓰니, 영역을 가르려면 컴포넌트로 감싸야 해요. JSX 안에서 reset 을 한 번만 쓰면 컴포넌트가 깔끔하고, 여러 곳에서 reset 을 참조하거나 로직과 섞어야 하면 useQueryErrorResetBoundary 훅이 편해요.
안 돼요. invalidateQueries 는 쿼리의 에러 상태를 그대로 두고, fallback 이 떠 있는 동안에는 구독하는 컴포넌트가 없어서 refetch 대상에서도 빠져요. 상태를 비워야 하면 resetQueries 에 쿼리 키를 좁혀서 넘기세요.

참고 자료

관련 글