Next.js Documentation (Official Mirror)

The forbidden function throws an error that renders a Next.js 403 error page. It's useful for handling authorization errors in your application. You can customize the UI using the forbidden.js file.

To start using forbidden, enable the experimental authInterrupts configuration option in your next.config.js file:

filename="next.config.ts" switcher

const nextConfig: NextConfig = {
  experimental: {
    authInterrupts: true,
  },
}

export default nextConfig

filename="next.config.js" switcher
module.exports = {
  experimental: {
    authInterrupts: true,
  },
}

forbidden can be invoked in Server Components, Server Functions, and Route Handlers.

tsx

filename="app/auth/page.tsx" switcher

export default async function AdminPage() {
  const session = await verifySession()

  // Check if the user has the 'admin' role
  if (session.role !== 'admin') {
    forbidden()
  }

  // Render the admin page for authorized users
  return <></>
}

jsx

filename="app/auth/page.js" switcher

export default async function AdminPage() {
  const session = await verifySession()

  // Check if the user has the 'admin' role
  if (session.role !== 'admin') {
    forbidden()
  }

  // Render the admin page for authorized users
  return <></>
}

Good to know

The forbidden function cannot be called in the root layout.

Examples

Role-based route protection

You can use forbidden to restrict access to certain routes based on user roles. This ensures that users who are authenticated but lack the required permissions cannot access the route.

tsx

filename="app/admin/page.tsx" switcher

export default async function AdminPage() {
  const session = await verifySession()

  // Check if the user has the 'admin' role
  if (session.role !== 'admin') {
    forbidden()
  }

  // Render the admin page for authorized users
  return (
    <main>
      <h1>Admin Dashboard</h1>
      <p>Welcome, {session.user.name}!</p>
    </main>
  )
}

jsx

filename="app/admin/page.js" switcher

export default async function AdminPage() {
  const session = await verifySession()

  // Check if the user has the 'admin' role
  if (session.role !== 'admin') {
    forbidden()
  }

  // Render the admin page for authorized users
  return (
    <main>
      <h1>Admin Dashboard</h1>
      <p>Welcome, {session.user.name}!</p>
    </main>
  )
}

Mutations with Server Actions

When implementing mutations in Server Actions, you can use forbidden to only allow users with a specific role to update sensitive data.

filename="app/actions/update-role.ts" switcher
'use server'


export async function updateRole(formData: FormData) {
  const session = await verifySession()

  // Ensure only admins can update roles
  if (session.role !== 'admin') {
    forbidden()
  }

  // Perform the role update for authorized users
  // ...
}

filename="app/actions/update-role.js" switcher
'use server'


export async function updateRole(formData) {
  const session = await verifySession()

  // Ensure only admins can update roles
  if (session.role !== 'admin') {
    forbidden()
  }

  // Perform the role update for authorized users
  // ...
}

Version History

Version	Changes
`v15.1.0`	`forbidden` introduced.

filename="app/auth/page.tsx" switcher export default async function AdminPage() { const session = await verifySession() // Check if the user has the 'admin' role if (session.role !== 'admin') { forbidden() } // Render the admin page for authorized users return <></> }

filename="app/auth/page.js" switcher export default async function AdminPage() { const session = await verifySession() // Check if the user has the 'admin' role if (session.role !== 'admin') { forbidden() } // Render the admin page for authorized users return <></> }

Examples

Role-based route protection

You can use forbidden to restrict access to certain routes based on user roles. This ensures that users who are authenticated but lack the required permissions cannot access the route.

tsx

filename="app/admin/page.tsx" switcher

export default async function AdminPage() {
  const session = await verifySession()

  // Check if the user has the 'admin' role
  if (session.role !== 'admin') {
    forbidden()
  }

  // Render the admin page for authorized users
  return (
    <main>
      <h1>Admin Dashboard</h1>
      <p>Welcome, {session.user.name}!</p>
    </main>
  )
}

jsx

filename="app/admin/page.js" switcher

export default async function AdminPage() {
  const session = await verifySession()

  // Check if the user has the 'admin' role
  if (session.role !== 'admin') {
    forbidden()
  }

  // Render the admin page for authorized users
  return (
    <main>
      <h1>Admin Dashboard</h1>
      <p>Welcome, {session.user.name}!</p>
    </main>
  )
}

Mutations with Server Actions

When implementing mutations in Server Actions, you can use forbidden to only allow users with a specific role to update sensitive data.

filename="app/actions/update-role.ts" switcher
'use server'


export async function updateRole(formData: FormData) {
  const session = await verifySession()

  // Ensure only admins can update roles
  if (session.role !== 'admin') {
    forbidden()
  }

  // Perform the role update for authorized users
  // ...
}

filename="app/actions/update-role.js" switcher
'use server'


export async function updateRole(formData) {
  const session = await verifySession()

  // Ensure only admins can update roles
  if (session.role !== 'admin') {
    forbidden()
  }

  // Perform the role update for authorized users
  // ...
}

Version

Changes

v15.1.0

forbidden introduced.