できない.dev

React Error Boundary で非同期 / イベントハンドラのエラーがキャッチできない

Error Boundary は子ツリーのレンダリング中・ライフサイクル・コンストラクタで投げられた例外しか捕まえない。
イベントハンドラや非同期 / setTimeout のエラーは別途 try/catch して setState で再投入する必要がある。

公開: 更新:

症状できない
node bad_handler.js
before click: screen="send"
window error イベント: handler failed
after click : screen="send"

2026-10-14 に node:20(React 19.3.0 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

React の Error Boundary が「呼ばれない」と感じるとき、ほぼ全てはイベントハンドラ・非同期処理・SSR 中のエラーである。
これらは仕様上、Error Boundary の捕捉対象から外れている。
レンダリング経路に「エラーを再投入」する処理を自分で書く必要がある。

実行例

実際に上記の手順を node:20(React 19.3.0・jsdom 上で描画)で動かした。
onClick の中で throw した場合は window の error イベントに、async のハンドラで reject した場合は unhandledRejection にエラーが流れた。
どちらも Error Boundary のフォールバックは出ず、ボタンのままだった。
try/catch で受けて setState し、次のレンダーで throw する構成にすると、クリック後の画面が fallback: submit failed に切り替わった。

$ node bad_handler.js
before click: screen="send"
window error イベント: handler failed
after click : screen="send"
$ node bad_async.js
before click: screen="send"
unhandledRejection: submit failed
after click : screen="send"
$ node solve_state.js
before click: screen="send"
after click : screen="fallback: submit failed"

— 2026-10-14 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-14 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • React 19.3.0

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. イベントハンドラは try/catch + setState

function Form() {
  const [error, setError] = useState<Error | null>(null);
  if (error) throw error;  // 次のレンダーで Error Boundary に流す
 
  async function onSubmit() {
    try {
      await submit();
    } catch (e) {
      setError(e as Error);
    }
  }
  return <button onClick={onSubmit}>送信</button>;
}

Error Boundary が捕捉するのは、レンダー時の throw だけである。
React 公式ドキュメント(新しいタブで開く) でも明示されているとおり、この「state にしてから throw」パターンが標準になっている。

2. react-error-boundary のヘルパを使う

import { useErrorBoundary } from "react-error-boundary";
 
function MyComp() {
  const { showBoundary } = useErrorBoundary();
  async function load() {
    try {
      const data = await fetch("/api").then((r) => r.json());
      // ...
    } catch (e) {
      showBoundary(e);
    }
  }
  // ...
}

ライブラリが内部で「エラーを state にしてから throw」を吸収してくれる。

3. 非同期エラーをグローバルに拾う

最後の砦として、window.addEventListener("unhandledrejection", ...) でログ収集する。
ただし UI を切り替えたいなら、個別に Error Boundary に流す。

4. SSR / フレームワーク特有のフックを使う

Next.js の App Router なら error.tsx、Pages Router なら _error.tsx、Remix なら ErrorBoundary export を使う。
クライアントの Error Boundary とは独立した仕組みなので混同しない。

よくある原因

  1. <button onClick={() => { throw new Error("x"); }}> のように、イベントハンドラ内で投げている
  2. useEffect 内で await fetch(...) し、reject をそのまま放置している
  3. setTimeout(() => { throw new Error("x"); }, 0) のように、別ティック上で投げている
  4. SSR 中(サーバー実行)に投げたものを Error Boundary に流れると期待している
  5. Error Boundary 自身(同じコンポーネント)で投げたエラーをキャッチしようとしている