Role-based access control
A logged-in user attempts to open an admin route without the admin role.
Next.js 16+ · Function
forbidden
forbidden() stops a route segment with a 403 response when the current user is authenticated but lacks permission. Next.js renders the nearest forbidden UI and marks the response noindex.
How it works
Import forbidden from next/navigation and call it during the server render path when an authenticated user lacks permission. Next.js throws an internal 403 interruption, stops rendering that route segment, and displays the nearest forbidden.js or forbidden.tsx UI.
Syntax
forbidden(): neverReturns
Never returns; it throws a 403 interruption that renders the forbidden UI.
Key points
- Use forbidden() when a signed-in user lacks authorization for a resource.
- The current route segment stops rendering immediately after the call.
- The generated forbidden response is marked not to be indexed by search engines.
- The API is available across these server-side App Router contexts.
- Add a forbidden.js or forbidden.tsx file to provide custom access-denied UI.
Common mistakes
- Do not invoke forbidden from the root layout.
- Call forbidden() directly; it never returns.
- Keep the call in the render path or in a function awaited by the component.
Example: Reject unauthorized roles
import { forbidden } from 'next/navigation'
export default async function AdminPage() {
const user = await getUser()
if (user.role !== 'admin') {
forbidden()
}
return <h1>Admin area</h1>
}The page aborts rendering for non-admin users and displays the route's forbidden UI.
When to use it
Resource authorization
A user can access the application but lacks permission for a particular resource.
Server-side authorization checks
A server-side mutation detects insufficient permissions before completing the operation.
Interview questions
QWhat does forbidden() do?
forbidden() is an authorization interruption imported from next/navigation. It throws a 403 error, terminates rendering of the current route segment, and renders the matching forbidden UI.
Follow-up: What happens to indexing? Next.js adds a noindex robots meta tag to the resulting page.
QHow is the forbidden UI customized?
The route must be covered by a forbidden.js or forbidden.tsx file to customize its UI. That file is placed alongside the relevant route segment.
Follow-up: Can the root layout call forbidden()? No; the documentation explicitly excludes the root layout.
QHow is forbidden enabled and where can it run?
The API is experimental in the documented release and requires the experimental authInterrupts option in next.config.js. It can be used in Server Components, Server Functions, and Route Handlers.
Follow-up: What is the status code? It represents a 403 interruption, although response behavior can depend on whether headers have already been sent.
Related
forbidden.jsunauthorizedauthInterruptsnotFound