unstable_rethrow | Next.js

unstable_rethrow は、アプリケーションコードでスローされたエラーを処理しようとする際に、Next.js が内部でスローするエラーをキャッチしないようにするために使用できます。

例えば、notFound 関数を呼び出すと、Next.js の内部エラーがスローされ、not-found.js コンポーネントがレンダリングされます。しかし、try/catch ブロック内で使用すると、エラーがキャッチされてしまい、not-found.js のレンダリングが妨げられます:

@/app/ui/component.tsx

import { notFound } from 'next/navigation'

export default async function Page() {
  try {
    const post = await fetch('https://.../posts/1').then((res) => {
      if (res.status === 404) notFound()
      if (!res.ok) throw new Error(res.statusText)
      return res.json()
    })
  } catch (err) {
    console.error(err)
  }
}

unstable_rethrow API を使用すると、内部エラーを再スローして期待される動作を継続できます:

@/app/ui/component.tsx

import { notFound, unstable_rethrow } from 'next/navigation'

export default async function Page() {
  try {
    const post = await fetch('https://.../posts/1').then((res) => {
      if (res.status === 404) notFound()
      if (!res.ok) throw new Error(res.statusText)
      return res.json()
    })
  } catch (err) {
    unstable_rethrow(err)
    console.error(err)
  }
}

以下の Next.js API は、Next.js 自体によって再スローされ処理されるべきエラーをスローします:

ルートセグメントが静的でない場合にエラーをスローするようにマークされている場合、Dynamic API 呼び出しも同様に開発者によってキャッチされるべきではないエラーをスローします。Partial Prerendering (PPR) もこの動作に影響することに注意してください。これらの API は以下の通りです:

cookies
headers
searchParams
fetch(..., { cache: 'no-store' })
fetch(..., { next: { revalidate: 0 } })

知っておくと良いこと:

このメソッドは、catch ブロックの先頭で呼び出し、エラーオブジェクトを唯一の引数として渡す必要があります。また、Promise の .catch ハンドラー内でも使用できます。

エラーをスローする API の呼び出しが try/catch でラップされていないことを確認すれば、unstable_rethrow を使用する必要はありません。

リソースのクリーンアップ（インターバルやタイマーのクリアなど）は、unstable_rethrow の呼び出し前に実行するか、finally ブロック内で行う必要があります。