unauthorized.tsx in Next.js — Custom 401 UI for Unauthenticated Access

1. What Is unauthorized.tsx?

unauthorized.tsx is a special file in Next.js used to render a custom UI when the unauthorized() function is triggered. It’s useful for showing login prompts or access-denied messages to unauthenticated users.

2. Behavior and Status Code

• When unauthorized() is called, Next.js renders unauthorized.tsx
• The response automatically includes a 401 Unauthorized status code
• This feature is currently experimental and not recommended for production

3. Defining unauthorized.tsx

Create a file at app/unauthorized.tsx and export a default component. It should not accept any props:

// app/unauthorized.tsx
import Login from '@/app/components/Login'

export default function Unauthorized() {
  return (
    <main>
      <h1>401 - Unauthorized</h1>
      <p>Please log in to access this page.</p>
      <Login />
    </main>
  )
}

4. Triggering unauthorized.tsx

Use the unauthorized() function inside a Server Component to redirect unauthenticated users:

// 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>
}

5. Use Cases

• Displaying login UI for protected routes
• Customizing the 401 error experience
• Improving UX for unauthenticated users

6. Limitations

• unauthorized.tsx does not accept props
• Feature is experimental and may change in future versions
• Not recommended for production without fallback logic

Conclusion

unauthorized.tsx in Next.js provides a clean way to handle unauthenticated access by rendering a custom login UI and returning a 401 status code. While still experimental, it offers a promising approach to access control and user experience design in modern web apps.