Functions: unauthorized | Next.js

MenuUsing App RouterFeatures available in /appLatest Version16.1.6API ReferenceFunctionsunauthorizedCopy pageunauthorizedThis feature is currently experimental and subject to change, it's not recommended for production. Try it out and share your feedback on GitHub.Last updated February 27, 2026The unauthorized function throws 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. To start using unauthorized, enable the experimental authInterrupts configuration option in your next.config.js file: next.config.tsTypeScriptJavaScriptTypeScriptimport type { NextConfig } from 'next' const nextConfig: NextConfig = { experimental: { authInterrupts: true, }, } export default nextConfig unauthorized can be invoked in Server Components, Server Functions, and Route Handlers. app/dashboard/page.tsxTypeScriptJavaScriptTypeScriptimport { verifySession } from '@/app/lib/dal' import { unauthorized } from 'next/navigation' export default async function DashboardPage() { const session = await verifySession() if (!session) { unauthorized() } // Render the dashboard for authenticated users return ( <main> <h1>Welcome to the Dashboard</h1> <p>Hi, {session.user.name}.</p> </main> ) } Good to know The unauthorized function cannot be called in the root layout. Examples Displaying login UI to unauthenticated users You can use unauthorized function to display the unauthorized.js file with a login UI. app/dashboard/page.tsxTypeScriptJavaScriptTypeScriptimport { 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.tsxTypeScriptJavaScriptTypeScriptimport 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> ) } Mutations with Server Actions You can invoke unauthorized in Server Actions to ensure only authenticated users can perform specific mutations. app/actions/update-profile.tsTypeScriptJavaScriptTypeScript'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() } // Proceed with mutation // ... } Fetching data with Route Handlers You can use unauthorized in Route Handlers to ensure only authenticated users can access the endpoint. app/api/profile/route.tsTypeScriptJavaScriptTypeScriptimport { NextRequest, NextResponse } from 'next/server' import { verifySession } from '@/app/lib/dal' import { unauthorized } from 'next/navigation' export async function GET(req: NextRequest): Promise<NextResponse> { // Verify the user's session const session = await verifySession() // If no session exists, return a 401 and render unauthorized.tsx if (!session) { unauthorized() } // Fetch data // ... } Version History VersionChangesv15.1.0unauthorized introduced.unauthorized.jsAPI reference for the unauthorized.js special file.Was this helpful?