Capítulo 178 de 456

unauthorized

Core Idea

Lança um erro que renderiza uma página 401 do Next.js, para tratar casos de autenticação ausente; requer a flag experimental authInterrupts.

Key Concepts

  • unauthorized(): lança NEXT_HTTP_ERROR_FALLBACK;401 e termina o render do segmento onde foi chamado; injeta <meta name="robots" content="noindex" />.
  • authInterrupts (experimental): precisa ser habilitada em next.config.js (experimental: { authInterrupts: true }) antes de usar unauthorized.
  • Deve ser chamado no render path: componente ou função awaitada por componente; em promise não aguardada, nada captura e nenhuma UI renderiza.
  • Restrição: não pode ser chamado no root layout.
  • Status experimental: não recomendado para produção conforme a doc.

Code Examples

// next.config.ts
const nextConfig: NextConfig = {
  experimental: { authInterrupts: true },
}
export default nextConfig
  • O que demonstra: habilitar a flag necessária antes de usar unauthorized().
// 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 <main><h1>Welcome to the Dashboard</h1></main>
}
  • O que demonstra: bloquear render de página quando sessão não existe.
// Checagem dentro de Suspense para manter shell visível
async function getAccount() {
  const session = await verifySession()
  if (!session) unauthorized()
  return db.accounts.findByUserId(session.userId)
}

async function AccountDetails() {
  const account = await getAccount()
  return <p>Signed in as {account.email}</p>
}
  • O que demonstra: checagem de auth dentro da camada de dados, permitindo shell/loading visível enquanto a sessão resolve.

Reference Tables

VersionChanges
v15.1.0unauthorized introduzido

Anti-patterns

  • Chamar no root layout: não suportado.
  • try/catch sem unstable_rethrow: suprime o erro e a UI de unauthorized não renderiza.
  • Esperar status 401 real após streaming iniciado: se a checagem roda dentro de <Suspense>, a resposta já começou como 200; para 401 real, cheque em proxy antes do stream (com Cache Components).

Key Takeaways

  1. Exige habilitar authInterrupts no config antes de funcionar.
  2. Não é permitido no root layout — coloque a checagem em layouts/páginas aninhadas.
  3. Use unauthorized.js para customizar a UI (ex.: exibir formulário de login).

Connects To

  • unauthorized.js: arquivo de convenção para a UI de 401.
  • authInterrupts: flag de config obrigatória.
  • forbidden / notFound: funções irmãs para outros status HTTP.
AnteriorrevalidateTagPróximounstable_cache