Next.js - unauthorized() Function

---

---

The unauthorized() Function

The Next.js unauthorized() function is used to throw an error that renders a Next.js 401 error page. It's useful for handling authorization errors in your application. You can customize the UI using the unauthorized.js file.

Syntax

The syntax for the unauthorized() function is as follows:

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
 
export default async function DashboardPage() {
    const session = await verifySession()
    
    // if session is not verified, throw an error
    if (!session) {
        unauthorized()
    }
}

Parameters

The unauthorized() function accepts no parameters.

Return Value

The unauthorized() function does not return any value.

Enable Unauthorized Function

The unauthorized() function is an experimental feature in Next.js. To enable it, you need to set 'authInterrupts' configuration option in your next.config.js file.

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    authInterrupts: true,
  },
}
 
export default nextConfig

Example 1

You can use unauthorized function to display the unauthorized.js file with a login UI. The code below shows how to use the unauthorized() function to throw an error that renders the unauthorized.js file.

// app/dashboard/page.tsx

import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
 
export default async function DashboardPage() {
    const session = await verifySession()
    
    if (!session) {
        unauthorized()
    }
    
    return <div>Dashboard</div>
}

// app/unauthorized.js

import Login from '@/app/components/Login'
 
export default function UnauthorizedPage() {
  return (
    <main>
        <h1>401 - Unauthorized</h1>
        <p>Please log in to access this page.</p>
        <Login />
    </main>
  )
}

Output

The image below shows the output of the code snippet above. When we try to access the dashboard page without logging in, we get the unauthorized.js file with a login UI.

Example 2

You can invoke unauthorized in Server Actions to ensure only authenticated users can perform specific mutations. The code below shows how to perform a mutation that requires authentication.

'use server'
 
import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
import db from '@/app/lib/db'
 
export async function updateProfile(data: FormData) {
    const session = await verifySession()
    
    // If the user is not authenticated, return a 401
    if (!session) {
        unauthorized()
    }
}