メインコンテンツまでスキップ

エラーハンドリング

エラーは2つのカテゴリに分けることができます:予期されたエラー未キャッチ例外

  • 予期されたエラーを戻り値としてモデル化する:Server Actionsで予期されたエラーにはtry/catchを使用しないでください。これらのエラーを管理し、クライアントに返すにはuseFormStateを使います。
  • 予期しないエラーにはエラーボーダリを使用する:予期しないエラーを処理し、フォールバックUIを提供するには、error.tsxおよびglobal-error.tsxファイルを使用してエラーボーダリを実装します。

予期されたエラーの処理

予期されたエラーとは、サーバー側フォームバリデーションやリクエストの失敗など、アプリケーションの通常の操作中に発生する可能性があるエラーです。これらのエラーは明示的に処理し、クライアントに返すべきです。

Server Actionsからの予期されたエラーを処理する

useFormStateフックを使用して、Server Actionsの状態を管理し、エラーを処理します。このアプローチはtry/catchブロックを避け、予期されたエラーを例外としてスローするのではなく、戻り値としてモデル化します。

app/actions.ts
'use server'

import { redirect } from 'next/navigation'

export async function createUser(prevState: any, formData: FormData) {
const res = await fetch('https://...')
const json = await res.json()

if (!res.ok) {
return { message: '正しいメールアドレスを入力してください' }
}

redirect('/dashboard')
}

その後、useFormStateフックにアクションを渡し、返されるstateを使用してエラーメッセージを表示できます。

app/ui/signup.tsx
'use client'

import { useFormState } from 'react-dom'
import { createUser } from '@/app/actions'

const initialState = {
message: '',
}

export function Signup() {
const [state, formAction] = useFormState(createUser, initialState)

return (
<form action={formAction}>
<label htmlFor="email">Email</label>
<input type="text" id="email" name="email" required />
{/* ... */}
<p aria-live="polite">{state?.message}</p>
<button>Sign up</button>
</form>
)
}

Good to know: これらの例は、Next.js App Routerと一緒にバンドルされているReactのuseFormStateフックを使用しています。React 19を使用している場合は、useActionStateを代わりに使用してください。詳細についてはReactドキュメントを参照してください。

返された状態を使用して、クライアントコンポーネントからトーストメッセージを表示することもできます。

Server Componentsからの予期されたエラーを処理する

Server Component内でデータを取得する際には、応答を利用してエラーメッセージを条件付けてレンダリングするか、redirectを使用してください。

app/page.tsx
export default async function Page() {
const res = await fetch(`https://...`)
const data = await res.json()

if (!res.ok) {
return 'エラーが発生しました。'
}

return '...'
}

未キャッチ例外

未キャッチ例外は、アプリケーションの通常のフロー中に発生するはずのないバグや問題を示す予期しないエラーです。これらはエラーをスローすることで処理され、エラーボーダリによってキャッチされます。

  • 共通: root レイアウト下の未キャッチエラーをerror.jsで処理します。
  • オプション: ネストされたerror.jsファイル(例:app/dashboard/error.js)で詳細な未キャッチエラーを処理します。
  • まれ: root レイアウトで未キャッチエラーをglobal-error.jsで処理します。

エラーボーダリを使用する

Next.jsはエラーボーダリを使用して未キャッチ例外を処理します。エラーボーダリはそれらの子コンポーネント内のエラーをキャッチし、クラッシュしたコンポーネントツリーの代わりにフォールバックUIを表示します。

ルートセグメント内にerror.tsxファイルを追加し、Reactコンポーネントをエクスポートすることでエラーボーダリを作成します:

app/dashboard/error.tsx
'use client' // エラーボーダリはClient Componentsである必要があります

import { useEffect } from 'react'

export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
useEffect(() => {
// エラーをエラーレポートサービスにログします
console.error(error)
}, [error])

return (
<div>
<h2>何かがうまくいきませんでした!</h2>
<button
onClick={
// セグメントを再レンダリングすることで回復を試みます
() => reset()
}
>
Try again
</button>
</div>
)
}

エラーを親エラーボーダリまで伝播させたい場合は、errorコンポーネントのレンダリング時にthrowすることができます。

ネストされたルートでのエラー処理

エラーは最も近い親エラーボーダリに伝播します。これにより、ルート階層の異なるレベルにerror.tsxファイルを配置することで詳細なエラーハンドリングが可能になります。

ネストされたエラーコンポーネントの階層ネストされたエラーコンポーネントの階層

グローバルエラーの処理

あまり一般的ではありませんが、国際化を活用していても、root レイアウト内でapp/global-error.jsを使用してエラーを処理できます。グローバルエラーUIは、アクティブになったときにroot レイアウトまたはテンプレートを置き換えるため、自身の<html>および<body>タグを定義する必要があります。

app/global-error.tsx
'use client' // エラーボーダリはClient Componentsである必要があります

export default function GlobalError({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
// global-errorにはhtmlとbodyタグが含まれていなければなりません
<html>
<body>
<h2>何かがうまくいきませんでした!</h2>
<button onClick={() => reset()}>Try again</button>
</body>
</html>
)
}