unstable_rethrow

unstable_rethrow can be used to avoid catching internal errors thrown by Next.js when attempting to handle errors thrown in your application code.

For example, calling thenotFound function will throw an internal Next.js error and render thenot-found.js component. However, if used inside thetry block of atry/catch statement, the error will be caught, preventingnot-found.js from rendering:

import { notFound }from'next/navigation'exportdefaultasyncfunctionPage() {try {constpost=awaitfetch('https://.../posts/1').then((res)=> {if (res.status===404)notFound()if (!res.ok)thrownewError(res.statusText)returnres.json()    })  }catch (err) {console.error(err)  }}

You can useunstable_rethrow API to re-throw the internal error and continue with the expected behavior:

import { notFound, unstable_rethrow }from'next/navigation'exportdefaultasyncfunctionPage() {try {constpost=awaitfetch('https://.../posts/1').then((res)=> {if (res.status===404)notFound()if (!res.ok)thrownewError(res.statusText)returnres.json()    })  }catch (err) {unstable_rethrow(err)console.error(err)  }}

The following Next.js APIs rely on throwing an error which should be rethrown and handled by Next.js itself:

• notFound()
• redirect()
• permanentRedirect()

If a route segment is marked to throw an error unless it's static, a Dynamic API call will also throw an error that should similarly not be caught by the developer. Note that Partial Prerendering (PPR) affects this behavior as well. These APIs are:

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

Good to know:

• This method should be called at the top of the catch block, passing the error object as its only argument. It can also be used within a.catch handler of a promise.
• You may be able to avoid usingunstable_rethrow if you encapsulate your API calls that throw and let thecaller handle the exception.
• Only useunstable_rethrow if your caught exceptions may include both application errors and framework-controlled exceptions (likeredirect() ornotFound()).
• Any resource cleanup (like clearing intervals, timers, etc) would have to either happen prior to the call tounstable_rethrow or within afinally block.