9. error.tsx — 実行時エラーの受け皿

ページの処理中に予期しないエラーが起きたとき、画面全体が真っ白になる代わりに代替UIを出すには、app の各フォルダに error.tsx を置きます。これはそのフォルダ以下で起きたエラーを受け止めるエラーバウンダリとして働き、エラー時に default export したコンポーネントが表示されます。loading.tsx・not-found.tsx と並ぶ、もう1つの特別なファイルです。

error.tsx は、受け取った error オブジェクトでエラー内容を扱えます。実務ではエラーを記録(ログ送信)しつつ、ユーザーには分かりやすいメッセージと「やり直す」ボタンを見せるのが定番です。やり直しには再描画を試みる関数(下の例の unstable_retry)を使います。フォルダごとに置けるので、一部分だけが壊れても他の画面は生かしたまま、その範囲だけ代替表示にできます。

注意点は、error.tsx の先頭に "use client" が必要なことです(エラーバウンダリはクライアント側の仕組みのため)。また、これが受け止めるのは実行時に投げられたエラーで、URLが存在しない404は not-found.tsx 側の担当、と役割が分かれています。なお再試行用の関数名は Next.js のバージョンで変わることがあるため、実際に使うバージョンのドキュメントで確認しましょう。

サンプルコード(フレームワーク環境が必要なため表示のみ)

// app/dashboard/error.tsx — このフォルダ以下のエラーを受け止める
"use client"; // エラーバウンダリはClient Componentである必要がある

import { useEffect } from "react";

export default function Error({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string };
  unstable_retry: () => void;
}) {
  useEffect(() => {
    console.error(error); // エラー記録サービスへ送るなど
  }, [error]);

  return (
    <main>
      <h2>問題が発生しました</h2>
      {/* 再描画を試みて回復を図る */}
      <button onClick={() => unstable_retry()}>やり直す</button>
    </main>
  );
}

公式ドキュメントで詳しく ↗