vercel/next.js · error · Error

`unauthorized()` is experimental and only allowed to be used

Error message

`unauthorized()` is experimental and only allowed to be used when `experimental.authInterrupts` is enabled.

What it means

`unauthorized()` (unauthorized.ts:23-28) is gated behind the `experimental.authInterrupts` feature flag, injected at build time via `process.env.__NEXT_EXPERIMENTAL_AUTH_INTERRUPTS`. When the flag is false, calling `unauthorized()` throws this `Error` instead of the intended 401 access-fallback error. The function is intentionally experimental because its semantics (interrupting rendering to show an `unauthorized.js` boundary) are still in flux.

Source

Thrown at packages/next/src/client/components/unauthorized.ts:25

/**
 * @experimental
 * This function allows you to render the [unauthorized.js file](https://nextjs.org/docs/app/api-reference/file-conventions/unauthorized)
 * within a route segment as well as inject a tag.
 *
 * `unauthorized()` can be used in
 * [Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components),
 * [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers), and
 * [Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations).
 *
 *
 * Read more: [Next.js Docs: `unauthorized`](https://nextjs.org/docs/app/api-reference/functions/unauthorized)
 */

const DIGEST = `${HTTP_ERROR_FALLBACK_ERROR_CODE};401`

export function unauthorized(): never {
  if (!process.env.__NEXT_EXPERIMENTAL_AUTH_INTERRUPTS) {
    throw new Error(
      `\`unauthorized()\` is experimental and only allowed to be used when \`experimental.authInterrupts\` is enabled.`
    )
  }

  const error = new Error(DIGEST) as HTTPAccessFallbackError
  ;(error as HTTPAccessFallbackError).digest = DIGEST
  throw error
}

View on GitHub (pinned to 0ae8c72462)

Solutions

Enable the flag in next.config.js: `module.exports = { experimental: { authInterrupts: true } }`.
If you do not want experimental features, replace `unauthorized()` with a manual redirect to a login page or a `notFound()` call.
After enabling, rebuild (`next build`) so the env var is injected into the bundle.

Example fix

// before — next.config.js
module.exports = {}
// unauthorized() throws in code

// after — next.config.js
module.exports = {
  experimental: { authInterrupts: true },
}

Defensive patterns

Strategy: validation

Validate before calling

// Read your config before relying on unauthorized():
// next.config.js must contain experimental.authInterrupts = true
// Programmatically:
const cfg = require('./next.config.js')
if (!cfg.experimental?.authInterrupts) {
  throw new Error('Enable experimental.authInterrupts before using unauthorized()')
}

Prevention

Enable experimental.authInterrupts in next.config.js before using unauthorized()/forbidden().
Rebuild after changing experimental flags so the env var is injected.
Keep experimental flag usage documented in the project README to avoid surprises across environments.

When it happens

Trigger: Calling `unauthorized()` in a Server Component, Route Handler, or Server Action when `experimental.authInterrupts` is not enabled in `next.config.js`. The env var is false by default, so any project that hasn't opted in hits the throw.

Common situations: Copying sample code that uses `unauthorized()` without reading the experimental notice; enabling the flag in one environment but not another (e.g. production config differs); upgrading Next.js where the flag name or default changed.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/f32389cbc0b50536. Report an issue: GitHub.