Preserve framework control flow
A fetch or database operation is wrapped in try/catch and may call notFound() or redirect().
Next.js 16+ · Function
unstable_rethrow
Re-throws internal Next.js exceptions from a catch block so framework control flow—such as notFound() or redirect()—is preserved. Use it only when a catch block may receive both framework and application errors.
How it works
unstable_rethrow receives the caught error and rethrows it when it is an internal Next.js exception, preserving behaviors such as notFound() and redirect(). Application errors can continue through the catch block for logging or fallback handling.
Syntax
unstable_rethrow(error)Parameters
| Name | Type | Description |
|---|---|---|
error | unknown | The caught error or exception to inspect and potentially rethrow. |
Returns
No documented return value; framework-controlled errors are rethrown, while ordinary errors continue after the call.
Key points
- It prevents application catch logic from swallowing internal Next.js errors.
- Framework exceptions are rethrown so Next.js can complete its normal control flow.
- It is relevant to throwing control-flow APIs, including notFound(), redirect(), and permanentRedirect().
- The function works both in synchronous catch blocks and in promise catch handlers.
Common mistakes
- The API is unstable and may change, so avoid relying on it for production code without accepting that risk.
- Call it before logging, fallback handling, or other catch-block logic, and pass the caught error directly.
- Perform cleanup before calling it or in finally, because a framework exception may be rethrown immediately.
Example: Preserve Next.js control-flow errors
import { notFound, unstable_rethrow } from 'next/navigation'
export default async function Page() {
try {
const response = await fetch('https://example.com/posts/1')
if (response.status === 404) notFound()
if (!response.ok) throw new Error(response.statusText)
return <pre>{JSON.stringify(await response.json(), null, 2)}</pre>
} catch (error) {
unstable_rethrow(error)
console.error(error)
return <p>Could not load the post.</p>
}
}Use it at the start of a catch block so framework-controlled exceptions continue through Next.js while ordinary application errors can be handled locally.
When to use it
Protect promise catch handlers
A promise chain catches errors that might include Next.js internal exceptions.
Separate framework and application errors
Application errors need logging or a fallback, but framework exceptions must escape to Next.js.
Interview questions
QWhy use unstable_rethrow in a catch block?
It lets a catch block distinguish framework-controlled exceptions from application errors. Calling it with the caught error preserves Next.js handling for APIs such as notFound(), redirect(), and permanentRedirect().
Follow-up: What should happen to cleanup? Cleanup must run before unstable_rethrow or in a finally block, because the function may rethrow immediately.
QHow should unstable_rethrow be called?
Place unstable_rethrow(error) at the top of the catch block and pass the error as its only argument. This allows ordinary errors to proceed to local logging or fallback behavior while framework exceptions remain handled by Next.js.
Follow-up: Can it be used with promises? Yes; it can also be called inside a promise’s .catch handler.
QWhen is unstable_rethrow appropriate?
Use it only when the caught exceptions might include both application errors and framework-controlled exceptions. Relevant Next.js control-flow APIs include notFound(), redirect(), and permanentRedirect().
Follow-up: When should it not be added? Do not use it merely as general error handling when the catch block cannot receive framework-controlled exceptions.
Related
notFoundredirectpermanentRedirect