一覧画面を作っていました。上に検索ボックス、真ん中に本の一覧、下にお知らせ。 3つとも別々のコンポーネントです。
これは深掘りです。本線の順路ではありません。 本線のReactの画面の回で「動くと使えるの差は4つの状態」までやった人が、その4つ目(エラー)を画面に出そうとして、そもそも画面ごと消えてしまうところに当たったときに読む記事です。飛ばしても本線は進みます。
この記事のコマンドは、すべて VM(Ubuntu Server)の中で打ちます。 Windows の PowerShell ではありません。 画面の確認は、ホストの Windows のブラウザで行います。 本線で作った
~/react-demo/には触りません。 この記事では、まっさらな~/reactlab/を新しく作り、ポート 5183番で動かします。
ある日、一覧の中の1行で、こう書いていました。
<p>{book.author.name}</p>
author が入っていない本が1件だけ混ざっていました。 そこで例外が投げられます。
私が予想した結果は、「その1行だけ表示が崩れる」でした。よくても「一覧だけ出ない」。
実際に起きたのは、これです。
- 検索ボックスが消えた
- お知らせが消えた
- 背景色すら残らず、画面が真っ白になった
- エラーメッセージはどこにも出ていない
関係のない部分まで全部消えました。 最初は「ビルドが壊れた」「サーバーが落ちた」と思って、まったく別の場所を探しました。
これは事故ではありません。React 16以降の、意図された仕様です。 描画中に例外が投げられ、誰も受け止めなかったら、React はアプリ全体を画面から取り外します。
なぜそんな乱暴なことをするのか。理由は「壊れた画面を出し続けるほうが危ない」からです。
一覧の途中で例外が出たということは、そこから下の描画は全部止まっています。 そのまま中途半端に残すと、たとえば「削除」ボタンだけが残って、対象の行が消えている画面ができます。押せてしまいます。 銀行の残高が古いまま残ることもあります。
間違ったものを見せるくらいなら、何も見せない。 React はそう決めました。
だから、真っ白を避けるのは React の仕事ではなく、こちらの仕事です。そのための道具がエラー境界(Error Boundary)です。
対象レベル: 中級〜上級 / 区分: 発展
この記事でわかること
- 1つのコンポーネントが例外を投げると、アプリ全体が画面から消えること。React 16以降の仕様であって、バグでも設定ミスでもない
- 開発中と本番ビルドで、見え方がまるで違うこと。開発中は目立つエラー表示、本番は無言の真っ白。開発中しか見ていないと、この差に気づけない
- エラー境界は、いまでもクラスコンポーネントでしか書けないこと。フックでは書けない、React で唯一クラスが必要な場所
getDerivedStateFromErrorとcomponentDidCatchは役割が違うこと。片方は「何を出すか」、もう片方は「誰に知らせるか」- エラー境界が捕まえないものが4つあること(イベントハンドラの中・非同期の中・サーバー側の描画・境界自身)。「置いたのに真っ白のまま」の原因はほぼこれ
- 非同期のエラーは、
catchで state に入れて、描画中に投げ直すと境界に届くこと Suspenseは「読み込み中」、ErrorBoundaryは「失敗」で、2つで一組であること- データ取得の
Suspenseは、対応したライブラリが要ること。自分で書いたfetchでは、いくら待ってもfallbackは出ない - 本番でエラーを記録するときに、送ってはいけないものがあること
この記事でやること
~/reactlab/を新しく作り、ポート 5183番で起動する- わざと例外を投げるコンポーネントを置いて、真っ白を再現する。
npm run buildとpreviewで、本番の見え方も確かめる - エラー境界をクラスコンポーネントで自作し、全文を書いて、壊れる部分を囲む
- 境界が捕まえない4つを、1つずつ実際に投げて確認する
lazy+Suspenseでコード分割し、fallbackが出るところをネットワークを絞って見るSuspenseとErrorBoundaryを組み合わせて、読み込み中と失敗の両方を扱う
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| 例外(exception) | プログラムが「これ以上進めない」と判断して、処理を途中で放り投げること。JavaScript では throw で投げる |
| 投げる / 捕まえる(throw / catch) | 例外を出すことと、それを受け止めること。受け止める人がいないと、一番外まで飛んでいく |
| エラー境界(Error Boundary) | 子孫の描画中に投げられた例外を受け止めて、代わりの表示に差し替えるコンポーネント。React の仕組み |
| フォールバック(fallback) | 本来出すものが出せないときに、代わりに出すもの。エラー境界のエラー画面、Suspense の「読み込み中」がこれ |
| クラスコンポーネント | React の古い書き方。class ... extends Component と書く。いまは関数コンポーネントが基本だが、エラー境界だけは今もこれでしか書けない |
| ライフサイクルメソッド | クラスコンポーネントで、「描画される前」「描画されたあと」など決まった場面で React が呼んでくれるメソッド |
| アンマウント(unmount) | コンポーネントが画面から取り外されること。React は受け止められない例外が出ると、アプリ全体をアンマウントする |
| コード分割(code splitting) | JavaScript を1つの巨大なファイルにせず、必要になった時点で読み込む小さなファイルに分けること |
| チャンク(chunk) | コード分割でできた個々のファイルのかたまり。dist/assets/ の中に別ファイルとして出てくる |
Suspense | 子が「まだ準備できていない」と言っている間、代わりに fallback を出すReact の仕組み |
| 動的インポート(dynamic import) | import('./Heavy.jsx') の形。最初からではなく、実行中に読み込む |
1つだけ、先に頭に入れてください。 エラー境界は「エラーを消す道具」ではありません。 エラーが起きた範囲を、あらかじめ決めておく道具です。 境界を置いた分だけ、壊れたときに残る部分が増えます。 どこに置くかが、そのまま「何を守るか」になります。
① 準備 — reactlab を作る
本線で作った ~/react-demo/ は、そのまま残します。 この記事はわざと壊す手順しか出てこないので、別のプロジェクトでやります。
VM の中で打ちます。
「このまま依存を入れて起動しますか」と聞かれたら No(n)を選んでください。ポートを自分で決めたいからです。
eslint.config.js index.html package.json public README.md src vite.config.js
この一覧が出れば成功です。 npm install は初回だけ数分かかります(npmの回)。
ポートを開ける
この記事は 5183番を使います。開発サーバーと、本番ビルドの確認(preview)の両方で、この1つを使い回します。
Status: active
To Action From
-- ------ ----
22/tcp ALLOW Anywhere
5183/tcp ALLOW Anywhere
5183/tcp の行が出れば準備完了です。開けずに起動すると、ターミナルには「起動しました」と出るのに、ブラウザは読み込み中のままになります(ネットワークの回)。
起動する
ホストの Windows のブラウザで http://192.168.226.50:5183/ を開きます(IPは自分の値に。分からなければ VM の中で ip a)。Vite のロゴとカウンターが出れば成功です。
[スクリーンショット: 01_reactlab起動5183.png] ホストのブラウザで :5183 を開き、Vite + React の初期画面が出ているところを撮ってください。アドレスバーのポート番号が 5183 になっているのが見える形で。
止め方: ターミナルで Ctrl+C。
編集は VS Code から VM を開いて行います(VS Code Remote の回)。
コンソールを開けたままにする
この記事は、画面が真っ白になっている時間が長くなります。 真っ白の画面からは何も読み取れません。読むのはコンソールです。
ホストのブラウザで F12 を押して、Console タブを出したままにしてください(開発者ツールの回)。
後半で通信も見るので、Network タブがあることも確認しておいてください。
② 真っ白を再現する
まず、壊れるところを自分の目で見ます。 これを見ていないと、この先の話が全部ふわっとします。
わざと throw するコンポーネントを置く
src/Boom.jsx を新しく作ります。
export default function Boom() {
const book = { title: 'Reactの本' }
return <p>著者: {book.author.name}</p>
}
author が無いオブジェクトの .name を読んでいます。 これは実際にやりがちな形です(DOM操作の回で出た Cannot read properties of null と同じ系統のエラーです)。
src/App.jsx を、まるごとこう書き換えます。
import Boom from './Boom.jsx'
export default function App() {
return (
<div style={{ padding: 24, fontFamily: 'sans-serif' }}>
<h1>本棚</h1>
<input placeholder="検索" />
<hr />
<Boom />
<hr />
<footer>お知らせ: 明日メンテナンスです</footer>
</div>
)
}
見出し・検索ボックス・お知らせは、Boom とは何の関係もありません。 それでもどうなるかを見ます。
保存すると、ブラウザが自動で更新されます。
開発サーバーでの見え方
開発サーバーでは、エラーが目立つように表示されます。 Vite + React の構成なら、画面いっぱいに赤い枠のオーバーレイが出て、エラーメッセージとファイル名が読めるはずです。
[スクリーンショット: 02_開発中のエラー表示.png] :5183 で、エラーが画面に出ている状態を撮ってください。メッセージの文言が読める大きさで。
オーバーレイが出ないこともあります。 Vite やプラグインのバージョンによって、画面には何も出ず、コンソールにだけ出ることがあります。 出なくても問題ありません。 その場合は
F12のコンソールを見てください。 この記事で見たいのは「オーバーレイ」ではなく、「開発中は何かしら教えてくれる」という点だけです。
コンソール側には、こう出ます。
Uncaught TypeError: Cannot read properties of undefined (reading 'name')
at Boom (Boom.jsx:3:31)
The above error occurred in the <Boom> component:
at Boom
at div
at App
Consider adding an error boundary to your tree to customize error handling behavior.
注目してほしいのは最後の1行です。
Consider adding an error boundary to your tree (ツリーにエラー境界を追加することを検討してください)
React 自身が「境界を置け」と言っています。 つまり、真っ白は「境界を置いていない状態の既定の動作」なのです。
エラーは下から読みます(エラーの読み方の回)。ここでは The above error occurred in the <Boom> component が、どのコンポーネントで起きたかを教えてくれています。これは React が付けてくれる情報で、ただの console.error には出ません。
ここからが本題 — 本番ビルドでは真っ白
開発中の表示は、開発中だけのものです。 読者が見るのはビルドしたものです。別物です。
一度サーバーを止めます(Ctrl+C)。そしてビルドします。
vite v7.1.14 building for production...
✓ 32 modules transformed.
dist/index.html 0.46 kB │ gzip: 0.30 kB
dist/assets/index-B9x1p2Qa.css 1.39 kB │ gzip: 0.71 kB
dist/assets/index-Cm4kZ8vt.js 188.24 kB │ gzip: 59.31 kB
✓ built in 812ms
dist/ ができました。 ここに出てくるものが、実際に配る中身です(ビルドツールの回)。
その dist/ を、そのまま配ってみます。
ブラウザで http://192.168.226.50:5183/ を開き直します。
[スクリーンショット: 03_本番ビルドで真っ白.png] preview で開いた画面が真っ白なところを、コンソールも一緒に写る形で撮ってください。画面には何も無く、コンソールにだけ出ているのが分かる構図で。
画面はこうなります。
(何も表示されない)
赤い枠は出ません。文字も出ません。背景も白のままです。 h1 も、検索ボックスも、お知らせも、消えています。
コンソールにはこう出ます。
TypeError: Cannot read properties of undefined (reading 'name')
at hj (index-Cm4kZ8vt.js:48:9302)
ファイル名も関数名も潰れています。 これはミニファイ(圧縮)されているからで、ビルドの正常な結果です。
この違いが、この記事で一番危ないところです。
開発サーバー(npm run dev) | 本番ビルド(npm run build + preview) | |
|---|---|---|
| 画面 | エラーが画面に出る(オーバーレイ) | 完全に真っ白。何も出ない |
| コンソール | ファイル名・行番号・コンポーネント名が読める | 潰れた名前だけ。行番号は当てにならない |
| どのコンポーネントか | 出る | 出ないことがある |
| 気づけるか | すぐ気づく | 利用者は「壊れた」としか思わない。誰も報告してくれない |
「開発中は赤い画面が出るから大丈夫」は、間違いです。 赤い画面は、開発サーバーが親切で出しているだけです。本番には、それを出す人がいません。 エラー境界を置かないということは、「本番では真っ白でいい」と決めることと同じです。
もう1つ、地味に効くこと。 コンソールにだけ出るということは、利用者の手元でしか見えないということです。こちらのサーバーのログには、何も残りません(ログの回)。⑦で、これを送る話をします。
preview を Ctrl+C で止めて、開発サーバーに戻します。
③ エラー境界を自作する
ここだけはクラスコンポーネントでしか書けない
エラー境界は、フックでは書けません。
useErrorBoundary のようなフックは、React 本体にはありません(2026年時点)。class ... extends Component で書くしかありません。
React で「クラスコンポーネントを使わなければならない」場所は、いまここだけです。 逆に言うと、それ以外は全部関数コンポーネントで書けます。 クラスを覚え直す必要はありません。この1つの型を覚えるだけです。
なぜフックで書けないのか。理由はタイミングにあります。
フックは「そのコンポーネントが描画されるとき」に動きます。 ところがエラー境界がやりたいのは、「子の描画が途中で失敗したときに、割り込んで別のものを返す」ことです。自分の描画が終わったあと、子が壊れたときに呼ばれる必要があります。
その「決まった場面で React が呼んでくれるメソッド」の仕組みが、クラスにしか無いのです。
使うのは2つのメソッドだけ
| メソッド | いつ呼ばれるか | 何をするか |
|---|---|---|
static getDerivedStateFromError(error) | 子が例外を投げた直後、描画をやり直す前 | 返した値が state になる。「何を出すか」を決める。ここで通信や console.log をしない |
componentDidCatch(error, info) | フォールバックが描画されたあと | 記録する。「誰に知らせるか」を決める。通信してよいのはこちら |
なぜ2つに分かれているのか。 getDerivedStateFromError は static(インスタンスに属さない) で、React が「もう一度描画し直す」判断をする途中で呼ばれます。ここで副作用(通信・書き込み)を起こすと、描画のやり直しと絡んで二重に走ります。
だから、「表示を決める」と「外に知らせる」が、わざと別のメソッドに分けてあります。
- 片方だけでも動きます。
getDerivedStateFromErrorだけ書けば、フォールバックは出ます componentDidCatchだけ書くと、記録はされるが画面は真っ白のままです。これは実際にやりました(つまずいたところに書きます)
全文を書く
src/ErrorBoundary.jsx を新しく作ります。省略なしの全文です。
import { Component } from 'react'
export default class ErrorBoundary extends Component {
constructor(props) {
super(props)
this.state = { error: null }
}
static getDerivedStateFromError(error) {
// ここが返した値が、そのまま state になる
return { error }
}
componentDidCatch(error, info) {
// ここは「記録する」場所。通信してよいのはこちら
console.error('[ErrorBoundary]', error)
console.error('[ErrorBoundary] どこで:', info.componentStack)
}
handleRetry = () => {
this.setState({ error: null })
}
render() {
if (this.state.error) {
return (
<div style={{ padding: 16, border: '2px solid crimson', borderRadius: 8 }}>
<strong>{this.props.label ?? 'この部分'}は表示できませんでした</strong>
<p style={{ fontFamily: 'monospace', fontSize: 12 }}>
{String(this.state.error.message)}
</p>
<button onClick={this.handleRetry}>もう一度試す</button>
</div>
)
}
return this.props.children
}
}
読み方を、上から順に。
this.state = { error: null }— クラスではuseStateではなくthis.stateに持ちます。中身の考え方は同じです(propsとstateの回)static getDerivedStateFromError(error)—staticを消すと動きません。 画面には何も出ずに、ただ真っ白のままになります(開発中は Console に警告が1行出ます)info.componentStack— どのコンポーネントの中で起きたかの一覧。②で見たat Boom / at div / at Appの部分です。これが本番でエラーを追える唯一の手がかりになりますthis.props.children— エラーが無いときは、囲んだ中身をそのまま出すだけ。普段は何もしていませんString(this.state.error.message)—messageをそのまま画面に出すのは、練習だからです。 本番では出しません(⑦で書きます)
囲む
src/App.jsx を書き換えます。
import ErrorBoundary from './ErrorBoundary.jsx'
import Boom from './Boom.jsx'
export default function App() {
return (
<div style={{ padding: 24, fontFamily: 'sans-serif' }}>
<h1>本棚</h1>
<input placeholder="検索" />
<hr />
<ErrorBoundary label="本の一覧">
<Boom />
</ErrorBoundary>
<hr />
<footer>お知らせ: 明日メンテナンスです</footer>
</div>
)
}
保存して、ブラウザを見ます。
[スクリーンショット: 04_エラー境界のフォールバック.png] 見出し・検索ボックス・お知らせが残ったまま、真ん中だけ赤枠のエラー表示になっているところを撮ってください。
こうなれば成功です。
本棚
[検索 ]
──────────────
┌────────────────────────────────┐
│ 本の一覧は表示できませんでした │
│ Cannot read properties of ... │
│ [もう一度試す] │
└────────────────────────────────┘
──────────────
お知らせ: 明日メンテナンスです
同じ例外です。同じコンポーネントが投げています。 変えたのは囲んだことだけです。
エラー境界がやったのは、「エラーを直すこと」ではありません。 「壊れる範囲を、この
<ErrorBoundary>の内側までにする」と決めただけです。
preview でも確かめてください。 本番ビルドでも、ちゃんとこの赤枠が出ます。
②で真っ白だったものが、同じビルドの仕組みで、今度は赤枠になります。 確認したら Ctrl+C で止めて、npm run dev -- --host 0.0.0.0 --port 5183 に戻します。
「もう一度試す」は、たいてい効かない
押してみてください。 一瞬フォールバックが消えて、すぐまた同じエラーになります。
当然です。 state.error を null に戻すと、React はもう一度 <Boom /> を描画しようとします。 Boom は何も変わっていないので、また同じ例外を投げます。
「もう一度」が意味を持つのは、原因が外にあるときだけです。
- 通信が一時的に失敗した → もう一度で直る可能性がある
- データの形がおかしい → 何度押しても同じ
実務では、リトライと一緒に「原因を変える」必要があります。 よくやるのは、境界に key を渡して、key が変わったら境界ごと作り直す方法です。
<ErrorBoundary key={searchQuery} label="本の一覧">
<Books query={searchQuery} />
</ErrorBoundary>
key が変われば、React はそれを別のコンポーネントとみなして作り直します(keyの回と同じ理屈です)。state が初期値に戻るので、エラーも一緒に消えます。
どこに置くか
ここが設計の話です。 極端な2つを並べます。
A. アプリ全体に1つだけ置く
<ErrorBoundary label="このアプリ">
<App />
</ErrorBoundary>
B. 部分ごとに細かく置く
<ErrorBoundary label="検索"><SearchBox /></ErrorBoundary>
<ErrorBoundary label="本の一覧"><Books /></ErrorBoundary>
<ErrorBoundary label="お知らせ"><Notice /></ErrorBoundary>
| A: 全体に1つ | B: 細かく置く | |
|---|---|---|
| 壊れたときに残るもの | 何も残らない(フォールバックだけ) | 壊れていない部分は動き続ける |
| 書く量 | 1箇所 | 部分の数だけ |
| フォールバックの内容 | 「エラーが発生しました。再読み込みしてください」しか書けない | 「お知らせは表示できません」と具体的に書ける |
| 利用者が続けられるか | できない | 他の部分の操作は続けられる |
| 見落とし | 無い(必ずどこかで捕まる) | 境界の外で起きると、結局アプリ全体が落ちる |
結論から言うと、両方置きます。
- 一番外に、必ず1つ置く。 これは「最後の網」です。どこにも捕まらなかったものを、真っ白にはさせないため
- そのうえで、「ここが壊れても他は使えてほしい」単位に置く
2の単位の決め方は、コンポーネントの形ではなく、利用者の行動で決めます。
- サイドバーの広告が壊れても、本文は読めてほしい → 広告に置く
- 1つの記事のコメント欄が壊れても、記事は読めてほしい → コメント欄に置く
- 「入力中のフォーム」の内側に細かく置かない。 一部だけ生き残ると、送信できるのに中身が欠けた状態ができます(冒頭で書いた「押せてしまう」がこれです)
迷ったら、「ここが消えたまま、利用者が何かを押せてしまうか」を考えてください。 押せてしまうなら、境界はもっと外です。
④ エラー境界が捕まえないもの
ここが、この記事で一番よく事故が起きる場所です。
「境界を置いたのに、まだ真っ白になる」という相談の、ほぼ全部がこの4つです。
| 捕まえない場所 | なぜ | どうするか |
|---|---|---|
| イベントハンドラの中 | 描画中ではないから。React は描画しか監視していない | try/catch で自分で捕まえる |
非同期(setTimeout / fetch / Promise) | 投げられた時点で、描画はとっくに終わっている | catch で state に入れ、描画中に投げ直す |
| サーバー側の描画(SSR) | クライアントの React が動く前の話 | サーバー側の仕組みで受ける(SSRの回) |
| 境界自身の中 | 自分で自分は捕まえられない | さらに外側に、もう1つ境界を置く |
表で読んでも入りません。1つずつ投げます。
①イベントハンドラの中 — 実演
src/App.jsx の <footer> の上に、ボタンを足します。
<ErrorBoundary label="ボタン">
<button onClick={() => { throw new Error('ボタンの中で投げた') }}>
押すと投げる
</button>
</ErrorBoundary>
押してください。
結果: フォールバックは出ません。 画面は何も変わりません。 コンソールにだけ、こう出ます。
Uncaught Error: ボタンの中で投げた
at onClick (App.jsx:14:38)
境界の内側に置いたのに、素通りしました。
理由は「描画中ではない」からです。 エラー境界は、React が描画をしている最中に投げられたものだけを見ています。ボタンを押したのは、描画が終わって、React が待機している時間です。React はそこを見ていません。
これは覚え方があります。 「React が呼んだ関数の中」なら捕まる。「ブラウザが呼んだ関数の中」なら捕まらない。 描画関数は React が呼びます。
onClickはブラウザが呼びます。
直し方は、素の JavaScript と同じ try/catch です。
function SaveButton() {
const handleClick = () => {
try {
throw new Error('保存に失敗しました')
} catch (e) {
alert(e.message) // 実際は state に入れて画面に出す
}
}
return <button onClick={handleClick}>保存</button>
}
「エラー境界があるから try/catch は要らない」は、間違いです。 イベントの中は、いまも try/catch の世界です。
②非同期の中 — 実演
src/Async.jsx を作ります。
import { useEffect } from 'react'
export default function Async() {
useEffect(() => {
setTimeout(() => {
throw new Error('1秒後に投げた')
}, 1000)
}, [])
return <p>1秒後に、非同期で投げます</p>
}
App.jsx に、境界で囲んで置きます。
<ErrorBoundary label="非同期">
<Async />
</ErrorBoundary>
1秒待ってください。
結果: フォールバックは出ません。 コンソールにだけ出ます。
Uncaught Error: 1秒後に投げた
at App.jsx:8:15
setTimeout に渡した関数を呼ぶのは、React ではなくブラウザのタイマーです。①と同じ理由です。
fetch の .then() の中も、まったく同じです(非同期処理の回)。取得の失敗は、エラー境界には届きません。 前回の記事で「取得のコードが200行になる」と書いたときの、あの error state が必要になるのはこのためです。
直し方の型が1つあります。 catch で state に入れて、次の描画中に投げ直すのです。
src/Async.jsx を書き換えます。
import { useState, useEffect } from 'react'
export default function Async() {
const [error, setError] = useState(null)
// ⚠️ ここが要。描画中に投げるので、エラー境界に届く
if (error) throw error
useEffect(() => {
const id = setTimeout(() => {
try {
throw new Error('1秒後に投げた(境界に届く版)')
} catch (e) {
setError(e)
}
}, 1000)
return () => clearTimeout(id)
}, [])
return <p>1秒後に、非同期で投げます</p>
}
1秒待つと、今度はフォールバックが出ます。
何をしたのか、順番に。
- 非同期の中で
catchして、例外を state にしまう setErrorで再描画が起きる- 描画関数の先頭で
if (error) throw error— 今度は React が呼んでいる最中なので、境界が捕まえる
if (error) throw errorを、useEffectの中に書かないでください。 それでは①②と同じで、届きません。 描画関数の本体(returnより前)に書きます。 「描画中に投げる」ことが目的なので、場所そのものが意味を持ちます。
clearTimeout の後片づけを入れているのは、多重に動かないためです(useEffectの回)。
③サーバー側の描画 — ここだけは実演できません
正直に書きます。この記事の構成では、これだけ再現できません。
いま作っているのは Vite の SPA で、HTML は空っぽの <div id="root"> だけです。描画は全部ブラウザの中で起きています。 サーバー側では、React は1行も動いていません。
中身が <div id="root"></div> だけなのが見えるはずです。 サーバー側の描画が無いことが、これで確かめられます(SSRの回で、この curl の結果が変わる話をしています)。
サーバー側で React を動かす構成(Next.js など)では、componentDidCatch は呼ばれません。 サーバー側の描画は一度きりで、「state を変えてやり直す」ができないからです。サーバー側の失敗は、サーバー側の仕組みで受けます。
ただし、境界が完全に無駄になるわけではありません。 サーバーで失敗した部分は、ブラウザ側でもう一度描画されるときに、そこで境界が捕まえます。
④境界自身の中 — 実演
これは怖いので、必ず一度見てください。
src/ErrorBoundary.jsx の render() の中、フォールバックの部分をわざと壊します。message ではなく、存在しないものを読みます。
<p style={{ fontFamily: 'monospace', fontSize: 12 }}>
{String(this.state.error.detail.reason)}
</p>
保存して、Boom のあるページを開きます。
結果: 画面が全部、真っ白に戻ります。 ②の状態と同じです。
Uncaught TypeError: Cannot read properties of undefined (reading 'reason')
at ErrorBoundary.render (ErrorBoundary.jsx:26:41)
フォールバックを描画している最中に、境界自身が投げました。 それを捕まえられる人は、その外側にしかいません。 外側に誰もいなければ、アプリ全体が消えます。
フォールバックの中では、凝ったことをしない。 エラーオブジェクトの中を掘らない。
error.response.data.messageのような読み方は、responseが無い例外で必ず落ちます 通信もしない。 状態も参照しない。 できるだけ、ただの文字列を出すだけにする
これが「一番外に必ず1つ置く」のもう1つの理由です。 細かい境界のフォールバックが壊れても、外側の網が受けます。
壊した行を、元に戻してください。
<p style={{ fontFamily: 'monospace', fontSize: 12 }}>
{String(this.state.error.message)}
</p>
4つを並べる
| 誰が関数を呼んだか | 境界 | 使う道具 | |
|---|---|---|---|
| 描画中 | React | ✅ 捕まえる | エラー境界 |
| イベントハンドラ | ブラウザ | ❌ | try/catch |
| 非同期・通信 | ブラウザ / Promise | ❌ | catch → state → 描画中に throw |
| サーバー側の描画 | サーバー | ❌ | サーバー側の仕組み |
| 境界自身の描画 | React | ❌(自分は無理) | 外側にもう1つ境界 |
表の1列目が全部です。 「React が呼んでいる最中か」だけで決まります。
⑤ react-error-boundary という選択肢
ここまで書いたクラスは、多くのプロジェクトで書かれています。 同じものを何度も書かなくていいように、react-error-boundary というライブラリがあります。FallbackComponent を渡すだけで境界が作れて、onError で記録でき、resetKeys を渡すと「そのキーが変わったら自動でリセット」まで面倒を見てくれます。 ③の最後で key を使ってやった作り直しが、そのまま機能として入っているものだと思ってください。中身は、いま書いたのとほぼ同じクラスコンポーネントです。
この記事では入れません。 理由は、getDerivedStateFromError と componentDidCatch の役割分担、そして④の「捕まえない4つ」を知らないまま入れると、「ライブラリを入れたのに真っ白になる」で必ず詰まるからです。ライブラリは境界を書く手間を減らすだけで、④は1つも解決しません。 自分で1回書いてから、2つ目のプロジェクトで入れてください。
⑥ Suspense
エラー境界は「失敗したとき」の話でした。 もう半分、「まだ来ていないとき」の話をします。
lazy でコード分割する
いまのビルドは、JavaScript が1本にまとまっています。②の npm run build の出力を思い出してください。
dist/assets/index-Cm4kZ8vt.js 188.24 kB
全部で1本。 利用者が絶対に開かない画面のコードも、最初に全部ダウンロードされています。
重い部品を1つ作ります。 src/Heavy.jsx。
export default function Heavy() {
const rows = Array.from({ length: 300 }, (_, i) => `行 ${i + 1}`)
return (
<div style={{ maxHeight: 160, overflow: 'auto', border: '1px solid #ccc' }}>
{rows.map((r) => <div key={r}>{r}</div>)}
</div>
)
}
これを、必要になるまで読み込まないようにします。 App.jsx を書き換えます。
import { lazy, Suspense, useState } from 'react'
import ErrorBoundary from './ErrorBoundary.jsx'
const Heavy = lazy(() => import('./Heavy.jsx'))
export default function App() {
const [show, setShow] = useState(false)
return (
<div style={{ padding: 24, fontFamily: 'sans-serif' }}>
<h1>本棚</h1>
<button onClick={() => setShow(true)}>重い表を開く</button>
<hr />
{show && (
<Suspense fallback={<p>読み込み中...</p>}>
<Heavy />
</Suspense>
)}
<hr />
<footer>お知らせ: 明日メンテナンスです</footer>
</div>
)
}
3つ、新しいものがあります。
import('./Heavy.jsx')— 動的インポート。その場では読み込まず、この関数が呼ばれたときに取りに行くlazy(...)— その「取りに行く」を、コンポーネントとして使える形に包む<Suspense fallback={...}>— 中身がまだ来ていない間、fallbackを代わりに出す
lazy は Suspense とセットです。 Suspense で囲まずに lazy のコンポーネントを描画すると、エラーになります。
fallback が出るところを、実際に見る
押してください。 ……たぶん一瞬で表になって、「読み込み中…」は見えません。
当たり前です。 VM の中のサーバーから、同じLAN内のブラウザに、数キロバイトを送っているだけです。速すぎます。
見るには、通信を遅くします。
F12で開発者ツールを開く- Network タブを開く
- 速度を選ぶところ(既定は
No throttling)で、Slow 4Gを選ぶ - 画面を再読み込みしてから、ボタンを押す
今度は「読み込み中…」が数秒出ます。
[スクリーンショット: 05_Suspenseのfallback.png] Network タブを Slow 4G にした状態で、「読み込み中…」が出ている瞬間を撮ってください。下の Network タブに、別ファイルのリクエストが走っているのも一緒に写る形で。
Network タブを見てください。 ボタンを押した瞬間に、Heavy.jsx のような、押す前には無かったファイルの通信が始まっているはずです(開発サーバーではソースのファイル名のまま届きます。npm run build したものなら Heavy-〇〇〇.js です)。これがコード分割の実物です。
ビルドでも確かめられます。
Heavy-D3kq81ba.js index-B9x1p2Qa.css index-CmZ4x7Tt.js
Heavy-〇〇〇.js が、別のファイルとして出ています。 ②では1本だったものが2本になりました。import() と書いた場所が、そのままファイルの切れ目になります。
Suspense と ErrorBoundary を組み合わせる
ここまでで、「まだ来ていない」は扱えました。 では、来なかったら?
ネットワークが切れた、ファイルが消えた、デプロイでファイル名が変わった。 import() は失敗します。 そして Suspense は、失敗を扱えません。 fallback が出たまま、永遠に終わらないか、真っ白になります。
だから、2つ重ねます。
<ErrorBoundary label="重い表">
<Suspense fallback={<p>読み込み中...</p>}>
<Heavy />
</Suspense>
</ErrorBoundary>
この記事では順番をこうします。 ErrorBoundary が外、Suspense が内です。
逆にしても、Heavy の読み込み失敗はいちばん近い ErrorBoundary が捕まえます。 変わるのは「読み込み中の表示」と「エラー表示」が、それぞれどの範囲を置き換えるかだけです。
この2つは、役割で覚えると混ざりません。
| 何を扱うか | 出るもの | 書き方 | |
|---|---|---|---|
Suspense | まだ来ていない | fallback(読み込み中) | 関数コンポーネント。React 標準 |
ErrorBoundary | 来なかった / 壊れた | 自分で書いたエラー表示 | クラスで自作 |
[スクリーンショット: 06_読み込み失敗のフォールバック.png] Network タブを Offline にしてからボタンを押し、「読み込み中…」ではなく赤枠のエラー表示に変わるところを撮ってください。
確認のしかた: 画面を再読み込みしてから、Network タブの速度のところで Offline を選び、そのあとでボタンを押します(先に Offline にして再読み込みすると、ページ自体が開けません)。Slow 4G のままだと成功してしまうので、必ず Offline にしてください。
赤枠のエラー表示が出れば成功です。 ErrorBoundary が、Suspense の失敗を受け止めました。
確認が終わったら、Network タブの速度を No throttling に必ず戻してください。 戻し忘れると、このあと全部が遅くて、原因を探すことになります(これも実際にやりました)。
データ取得の Suspense は、自分の fetch では動かない
ここが、この記事で一番誤解されているところです。
Suspense を知ると、必ずこう考えます。
// ⚠️ これは動きません
<Suspense fallback={<p>読み込み中...</p>}>
<Books /> {/* 中で fetch している */}
</Suspense>
Books の中で useEffect + fetch を書いても、fallback は一瞬も出ません。 Books は「まだ準備できていない」とは言わずに、普通に空の画面を返してしまうからです。
理由は、Suspense の仕組みにあります。
Suspenseは「待っている」を検知しません。 子が「まだ準備できていない」と、React に決まった形で申告したときだけ動きます。 その申告のしかたは、React の内部の仕組みです。 自分のfetchは、申告のしかたを知りません。
lazy が動いたのは、lazy が React 本体の一部で、その申告のしかたを知っているからです。
では、データ取得で Suspense を使うにはどうするか。
- 対応したライブラリを使う。 前回入れた TanStack Query には、
Suspenseに対応した取得のしかたが用意されています(前回の記事) - フレームワークの仕組みに乗る。 Next.js のサーバー側の取得などは、最初からこれに対応しています(SSRの回)
- React 19 の
useを使う。 ただし「Promise をキャッシュしておく」役は自分では書けないので、結局ライブラリかフレームワークが要ります
まとめると、こうです。
| やりたいこと | Suspense は使えるか |
|---|---|
コード分割(lazy) | ✅ 使える。今日から使える |
自分で書いた fetch の待ち | ❌ 使えない。isLoading を自分で書く |
| 対応ライブラリでのデータ取得 | ✅ 使える |
「Suspense があるから isLoading はもう要らない」は、間違いです。 lazy の話と、データ取得の話が混ざっています。
⑦ 本番でエラーを記録する
②で確かめたとおり、本番のエラーはコンソールにしか出ません。 コンソールは、利用者のブラウザの中にあります。 こちらからは見えません。
送る場所は componentDidCatch です。 ErrorBoundary.jsx の componentDidCatch を書き換えます。
componentDidCatch(error, info) {
console.error('[ErrorBoundary]', error)
fetch('/api/client-errors', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
message: error.message,
stack: error.stack,
componentStack: info.componentStack,
url: location.pathname, // ⚠️ 検索文字列は付けない
userAgent: navigator.userAgent,
at: new Date().toISOString(),
}),
}).catch(() => {
// ⚠️ 送信の失敗は、握りつぶす
})
}
3つ、意図があります。
getDerivedStateFromErrorではなくcomponentDidCatchに書く。 ③で書いたとおり、通信してよいのはこちらです- 最後の
.catch(() => {})。 エラーを送る処理が失敗して、それがまた例外になったら、エラーの無限ループになります。送信は失敗しても黙って諦めるのが正解です urlにlocation.pathnameを使い、location.hrefを使っていない。 理由は次です
送ってはいけないもの
エラーの調査に便利だからと、何でも詰めると事故になります。
| 送りたくなるもの | なぜ危ないか |
|---|---|
location.href そのまま | ?q= の検索語、?token= などが丸ごと入る。pathname だけにする |
| 入力中のフォームの中身 | 氏名・住所・パスワードがそのまま乗る。絶対に送らない |
localStorage の中身 | ログインしたままにするための情報が入っていることがある |
error.message をそのまま | バックエンドのエラーをそのまま入れていると、メールアドレスや内部のIDが混ざることがある |
| Cookie | 送る理由がない |
そして、それを本番のエラー画面に出さないこと。 ③で書いた String(this.state.error.message) は練習用です。本番のフォールバックは、こうします。
<strong>{this.props.label ?? 'この部分'}は表示できませんでした</strong>
<p>時間をおいて、もう一度お試しください。</p>
利用者に技術的なメッセージを見せないのは、親切のためだけではありません。エラーメッセージは、内部構造を教える手がかりになります(セキュリティの回)。
送り先は、自前でもSaaSでも構いません。 Sentry のようなサービスは、ミニファイされたスタックを元のファイル名に戻す仕組みまで持っています。 自前で受けるなら、②で見た「潰れた関数名」を自分で戻す用意が要ります。
境界の外側で起きたものも拾う
④で見たとおり、イベントと非同期は境界に来ません。 それも拾いたいなら、ブラウザの入口に張ります。 src/main.jsx に足します。
window.addEventListener('error', (e) => {
console.error('[window.error]', e.message)
})
window.addEventListener('unhandledrejection', (e) => {
console.error('[unhandledrejection]', e.reason)
})
error— どこにも捕まらなかった例外が来ますunhandledrejection—.catch()を書き忘れた Promise の失敗が来ます。これがいちばん取りこぼされます
これは「記録するため」であって、「画面を直すため」ではありません。 ここまで来た時点で、画面はもう壊れています。 画面を守るのは、あくまで境界のほうです。
つまずいたところ
componentDidCatch だけ書いて、真っ白のままだった
最初に書いた境界は、componentDidCatch だけでした。 コンソールには [ErrorBoundary] と出ているのに、画面は真っ白。 「境界が壊れている」と思って、30分クラスの中を読み直しました。
当たり前でした。 componentDidCatch は記録するだけで、state を変えません。 state が変わらないので、render() は this.props.children を返し続け、また同じ例外が出るという状態でした。
getDerivedStateFromError を足したら、一発で直りました。 2つの役割が違うというのは、こういう意味でした。
static を消したら、画面に何も出ずに真っ白に戻った
getDerivedStateFromError の static を、書き写すときに落としました。
画面には何のエラーも出ません。 ただ、境界が働かなくなるだけです。「さっきまで動いていたのに」と、まったく別の場所を疑いました。(開発中なら Console に getDerivedStateFromError() is defined as an instance method という警告が出ます。本番ビルドでは出ません)
React は static のほう(クラス自体に付いているほう)を見ています。 インスタンスのメソッドとして書いても、誰も呼びません。
エラー境界が「エラーを直してくれる」と思っていた
境界を置いたあと、Boom の中身を直さずに満足していました。 赤枠が出ているのは「対処済み」ではありません。
境界は、壊れたことを利用者から隠すための布です。布をかけたら、下のものを直す仕事が残ります。 ⑦で記録を送る話を入れたのは、これを忘れないためです。
try/catch で囲めば全部捕まると思って、描画関数を囲んだ
④の①を見たあと、逆に振れました。 「じゃあ描画関数の中身を全部 try/catch すればいいのでは」と思って、こう書きました。
function Books() {
try {
return <ul>{...}</ul>
} catch (e) {
return <p>エラー</p>
}
}
これは、ほぼ何も捕まえません。 return <ul>{...}</ul> は、その場では「JSXのオブジェクトを作る」だけです(JSXの回)。子コンポーネントが実際に描画されるのは、この関数が終わって React に返したあとです。try はとっくに抜けています。
子の描画中のエラーを捕まえられるのは、エラー境界だけです。そこは代わりがありません。
Suspense の fallback が一度も見えなくて、動いていないと思った
⑥で lazy を入れたあと、「読み込み中…」が一度も出ませんでした。 Suspense の書き方を間違えたと思って、1時間書き直しました。
速すぎただけでした。VM とホストは同じLANで、ファイルは数キロバイトです。
Network タブで Slow 4G にしたら、あっさり出ました。 「見えない」と「動いていない」は違うという、いつもの話でした。Network タブで通信が走っているかを先に見れば、1時間は使わずに済みました。
速度を Slow 4G に戻し忘れて、翌日ずっと遅かった
⑥のあと、No throttling に戻さずにブラウザを閉じました。 翌日、まったく別の作業でページが異常に遅く、VM のせいだと思って top や ss を見て回りました。
開発者ツールの設定は、タブを開き直しても残ることがあります。 「急に遅くなった」ときは、まず Network タブの速度を見てください。
エラー画面に error.message を出したまま、本番に近い形で公開しかけた
練習で書いた String(this.state.error.message) を、そのまま残していました。 バックエンドから返ってきたメッセージがそのまま画面に出る作りだったので、内部のテーブル名が画面に出ました。
気づいたのは偶然です。 練習で書いた「デバッグ用の表示」は、消す作業を工程に入れないと必ず残ります。
後片づけ
この記事で使った ~/reactlab/ は、実験用です。
まず、開発者ツールの Network タブの速度を No throttling に戻してください。 プロジェクトを消しても、ブラウザ側の設定は消えません。
次に、ブラウザのタブを閉じるか再読み込みしてください。 ④で張った setTimeout が残っている可能性があります。
サーバーを止めます。 起動しているターミナルで Ctrl+C を押します。npm run dev と npm run preview の両方を止めたか、確認してください。
確認: 何も返らなければ、止まっています。
ポートを閉じます。
確認: 一覧に 5183/tcp が残っていなければ成功です。
プロジェクトを消します。
確認: reactlab が消えていれば片づけ完了です。
本線のものが無事なことを、必ず確認してください。
App.css App.jsx assets components index.css main.jsx
~/react-demo/ は、この先の本線でも使うので消さないでください。
戻し方: もう一度試したくなったら、①の
npm create vite@latest reactlab -- --template reactからやるだけです。数分で戻せます。node_modulesだけ消して中身を残すならrm -rf ~/reactlab/node_modules、戻すのはcd ~/reactlab && npm installです(npmの回)。
まとめ
- 1つのコンポーネントが描画中に例外を投げると、アプリ全体が画面から取り外される。 React 16以降の意図された仕様で、バグではない
- 理由は「壊れた画面を出し続けるほうが危ない」から。 一部だけ消えた画面では、押してはいけないボタンが押せてしまう
- 開発サーバーと本番ビルドで見え方がまるで違う。 開発中はエラーが画面に出て、本番は無言の真っ白
- 本番のエラーは、利用者のコンソールにしか出ない。 こちらのログには何も残らない
- エラー境界は、いまもクラスコンポーネントでしか書けない。 React で唯一クラスが要る場所で、逆に言えばここ以外は要らない
getDerivedStateFromErrorは「何を出すか」、componentDidCatchは「誰に知らせるか」。 前者を書かないと、記録はされるのに真っ白のままstaticを落とすと、画面には何も出ずに境界が黙って無効になる(警告は開発中の Console にだけ出る)- 境界は「エラーを直す道具」ではなく「壊れる範囲を決める道具」。 どこに置くかが、そのまま「何を守るか」になる
- 一番外に必ず1つ置く。 そのうえで「ここが壊れても他は使えてほしい」単位に置く
- 入力中のフォームの内側に細かく置かない。 一部だけ生き残ると、欠けたまま送信できてしまう
- 境界が捕まえないものが4つある。 イベントハンドラ・非同期・サーバー側の描画・境界自身
- 見分け方は1つ。 「React が呼んだ関数の中か、ブラウザが呼んだ関数の中か」
- イベントの中は、いまも
try/catchの世界。 「境界があるから要らない」は間違い - 非同期は
catch→ state → 描画中にthrowで境界に届く。throwは描画関数の本体に書く。useEffectの中では届かない - 描画関数を
try/catchで囲んでも、子の描画中のエラーは捕まらない。returnした時点では、まだ描画されていない - フォールバックの中で凝らない。
error.response.dataのような掘り方は、必ずいつか落ちて、全体が真っ白になる react-error-boundaryは同じものを短く書ける。 ただし「捕まえない4つ」は1つも解決しない。自作してから入れるlazy+Suspenseでコード分割できる。import()と書いた場所が、そのままファイルの切れ目になるfallbackは速すぎて見えない。 Network タブでSlow 4Gにして初めて見えるSuspenseは「まだ来ていない」、ErrorBoundaryは「来なかった」。 順番はErrorBoundaryが外、Suspenseが内- データ取得の
Suspenseは、自分で書いたfetchでは動かない。 対応したライブラリかフレームワークが要る - 「
SuspenseがあるからisLoadingは要らない」は間違い。lazyの話とデータ取得の話が混ざっている - 本番のエラーは
componentDidCatchから送る。 送信の失敗は握りつぶす。でないとエラーの無限ループになる location.href・フォームの中身・localStorage・Cookie は送らない。pathnameだけで足りる- 利用者に技術的なエラーメッセージを見せない。 内部構造の手がかりになる
参考リンク
- roadmap.sh — React
- React 公式 — Component(getDerivedStateFromError と componentDidCatch)
- React 公式 — Suspense
- React 公式 — lazy
- React 公式 — use
- react-error-boundary(GitHub)
- npm — react-error-boundary
- TanStack Query — Suspense
- MDN — try…catch
- MDN — 動的インポート
- MDN — window の error イベント
- MDN — unhandledrejection イベント
- Chrome 開発者ツール — ネットワークの速度を絞る
- Vite 公式 — 本番用のビルド
- Vite 公式 — コマンドラインインターフェース
- Sentry
次に読む
この記事は 【深掘り】React の 14 / 24 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- エラー境界(クラスでしか書けない場所)
- lazy と Suspense
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント