{"record":{"id":"f32389cbc0b50536","repo":"vercel/next.js","slug":"unauthorized-is-experimental-and-only-allowed","errorCode":null,"errorMessage":"`unauthorized()` is experimental and only allowed to be used when `experimental.authInterrupts` is enabled.","messagePattern":"`unauthorized\\(\\)` is experimental and only allowed to be used when `experimental\\.authInterrupts` is enabled\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/next/src/client/components/unauthorized.ts","lineNumber":25,"sourceCode":"/**\n * @experimental\n * This function allows you to render the [unauthorized.js file](https://nextjs.org/docs/app/api-reference/file-conventions/unauthorized)\n * within a route segment as well as inject a tag.\n *\n * `unauthorized()` can be used in\n * [Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components),\n * [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers), and\n * [Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations).\n *\n *\n * Read more: [Next.js Docs: `unauthorized`](https://nextjs.org/docs/app/api-reference/functions/unauthorized)\n */\n\nconst DIGEST = `${HTTP_ERROR_FALLBACK_ERROR_CODE};401`\n\nexport function unauthorized(): never {\n  if (!process.env.__NEXT_EXPERIMENTAL_AUTH_INTERRUPTS) {\n    throw new Error(\n      `\\`unauthorized()\\` is experimental and only allowed to be used when \\`experimental.authInterrupts\\` is enabled.`\n    )\n  }\n\n  const error = new Error(DIGEST) as HTTPAccessFallbackError\n  ;(error as HTTPAccessFallbackError).digest = DIGEST\n  throw error\n}\n","sourceCodeStart":7,"sourceCodeEnd":34,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/client/components/unauthorized.ts#L7-L34","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before — next.config.js\nmodule.exports = {}\n// unauthorized() throws in code\n\n// after — next.config.js\nmodule.exports = {\n  experimental: { authInterrupts: true },\n}","handlingStrategy":"validation","validationCode":"// Read your config before relying on unauthorized():\n// next.config.js must contain experimental.authInterrupts = true\n// Programmatically:\nconst cfg = require('./next.config.js')\nif (!cfg.experimental?.authInterrupts) {\n  throw new Error('Enable experimental.authInterrupts before using unauthorized()')\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["experimental","auth","app-router","config"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}