エラーハンドリング

エラーは2つのカテゴリに分類できます。予期されたエラーと未処理の例外です。このページでは、Next.jsアプリケーションでこれらのエラーを処理する方法について説明します。

予期されたエラーの処理

予期されたエラーは、アプリケーションの正常な動作中に発生する可能性があるエラーです。例えば、サーバー側のフォーム検証やリクエスト失敗などが該当します。これらのエラーは明示的に処理し、クライアントに返す必要があります。

Server Functions

Server Functionsで予期されたエラーを処理するには、useActionStateフックを使用できます。

これらのエラーについては、try/catchブロックを使用してエラーをスローするのではなく、予期されたエラーを戻り値としてモデル化してください。

app/actions.ts

TypeScript

'use server'
 
export async function createPost(prevState: any, formData: FormData) {
  const title = formData.get('title')
  const content = formData.get('content')
 
  const res = await fetch('https://api.vercel.app/posts', {
    method: 'POST',
    body: { title, content },
  })
  const json = await res.json()
 
  if (!res.ok) {
    return { message: 'Failed to create post' }
  }
}

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

app/ui/form.tsx

TypeScript

'use client'
 
import { useActionState } from 'react'
import { createPost } from '@/app/actions'
 
const initialState = {
  message: '',
}
 
export function Form() {
  const [state, formAction, pending] = useActionState(createPost, initialState)
 
  return (
    <form action={formAction}>
      <label htmlFor="title">Title</label>
      <input type="text" id="title" name="title" required />
      <label htmlFor="content">Content</label>
      <textarea id="content" name="content" required />
      {state?.message && <p aria-live="polite">{state.message}</p>}
      <button disabled={pending}>Create Post</button>
    </form>
  )
}

Server Components

Server Component内でデータを取得する場合、レスポンスを使用して条件付きでエラーメッセージを表示したり、redirectを実行したりできます。

app/page.tsx

TypeScript

export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()
 
  if (!res.ok) {
    return 'There was an error.'
  }
 
  return '...'
}

見つからない

ルートセグメント内でnotFound関数を呼び出し、not-found.jsファイルを使用して404 UIを表示できます。

app/blog/[slug]/page.tsx

TypeScript

import { getPostBySlug } from '@/lib/posts'
 
export default async function Page({ params }: { params: { slug: string } }) {
  const { slug } = await params
  const post = getPostBySlug(slug)
 
  if (!post) {
    notFound()
  }
 
  return <div>{post.title}</div>
}

app/blog/[slug]/not-found.tsx

TypeScript

export default function NotFound() {
  return <div>404 - Page Not Found</div>
}

未処理の例外の処理

未処理の例外は、アプリケーションの通常のフロー中に発生してはならないバグや問題を示す予期しないエラーです。これらは、エラーバウンダリーで処理されるエラーをスローすることで処理する必要があります。

ネストされたエラーバウンダリー

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

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

app/dashboard/error.tsx

TypeScript

'use client' // エラーバウンダリーはクライアントコンポーネントである必要があります
 
import { useEffect } from 'react'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // エラーをエラーレポーティングサービスにログします
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // セグメントの再レンダリングを試みて回復を試みます
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

エラーは最も近い親エラーバウンダリーまでバブルアップします。これにより、ルートハイアラキーの異なるレベルにerror.tsxファイルを配置することで、きめ細かいエラー処理が可能になります。

エラーバウンダリーはイベントハンドラー内のエラーをキャッチしません。これらは、アプリ全体がクラッシュするのではなく、フォールバックUIを表示するためにレンダリング中のエラーをキャッチするように設計されています。

一般的に、イベントハンドラーまたは非同期コード内のエラーはエラーバウンダリーで処理されません。これらはレンダリング後に実行されるためです。

これらの場合を処理するには、エラーを手動でキャッチしてuseStateまたはuseReducerを使用して保存し、UIを更新してユーザーに通知してください。

'use client'
 
import { useState } from 'react'
 
export function Button() {
  const [error, setError] = useState(null)
 
  const handleClick = () => {
    try {
      // 失敗する可能性のある作業を実行します
      throw new Error('Exception')
    } catch (reason) {
      setError(reason)
    }
  }
 
  if (error) {
    /* フォールバックUIをレンダリングします */
  }
 
  return (
    <button type="button" onClick={handleClick}>
      Click me
    </button>
  )
}

useTransitionからのstartTransition内で未処理のエラーが発生した場合、最も近いエラーバウンダリーまでバブルアップすることに注意してください。

'use client'
 
import { useTransition } from 'react'
 
export function Button() {
  const [pending, startTransition] = useTransition()
 
  const handleClick = () =>
    startTransition(() => {
      throw new Error('Exception')
    })
 
  return (
    <button type="button" onClick={handleClick}>
      Click me
    </button>
  )
}

グローバルエラー

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

app/global-error.tsx

TypeScript

'use client' // エラーバウンダリーはクライアントコンポーネントである必要があります
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-errorはhtmlおよびbodyタグを含める必要があります
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

エラーハンドリング

予期されたエラーの処理

Server Functions

Server Components

見つからない

未処理の例外の処理

ネストされたエラーバウンダリー

グローバルエラー

API リファレンス

error.js

not-found.js

notFound

redirect