Not found, forbidden and unauthorized

A page for an order that isn't there

Every tea shop order has a page: order 1042 is at /orders/1042. One folder answers them all, app/orders/[id], as Dynamic routes showed. But a visitor can type any number. What should /orders/9999 show, when no order has that number?

Not an error screen: nothing broke. The order just doesn't exist. For that, Next.js has a function, notFound(), and a file, not-found.tsx. Here is the shop with both. Like every example in this lesson, it's a real Next.js 16.4.3 project, built with next build and run with next start. It was also opened in real Chrome: this order page sends its first part before it looks for the order, so its not-found screen is finished in the browser, and only Chrome can show it. The Steps tab opens on /orders/9999:

1import { notFound } from "next/navigation";2import { getOrder } from "../../_data/orders";3 4export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {5  const { id } = await params;6  const order = await getOrder(id);7  if (!order) notFound();8  return (9    <main>10      <h1>Order {order.id}</h1>11      <p>12        {order.boxes} boxes of {order.tea}13      </p>14    </main>15  );16}

Here is app/orders/[id]/page.tsx, line by line:

• Line 1 imports notFound from next/navigation.
• Line 5 waits for params and takes the order's number, id, out of it. For /orders/9999, id is "9999".
• Line 6 looks for the order with getOrder, from app/_data/orders.ts, a stand-in for the shop's database with two orders, 1042 and 1043.
• Line 7: if there's no order, notFound() stops the page. It works by throwing, so nothing after it runs, and you don't write return in front of it. TypeScript knows this too: on lines 10 and 12, order can't be undefined.

Now click app/orders/[id]/not-found.tsx. It's an ordinary component that takes no props: line 6 is the heading Order not found, and line 8 links back to the shop. The loading.tsx beside it is the loading state from Loading UI: the order page waits for params, and with no list of order numbers during the build, Next.js only learns the number when a request comes in.

In the Steps tab, step 1 opened /orders/9999 and showed Order not found, Check the number on your receipt. and the link, under the root layout's Tea shop link. The address stayed /orders/9999. Step 2 opened /orders/1042, which showed Order 1042 and 2 boxes of Green tea. Now open the Network tab and pick /orders/9999. Two things there may surprise you: the status is 200, not 404, and the HTML holds only Loading your order…, plus a tag, <meta name="robots" content="noindex">. Both come from streaming, sending a page in parts, as in Loading UI: the layout and the loading state went out first, with status 200, before the page ran and called notFound(). React then drew not-found.tsx in the browser.

Which not-found page shows

notFound() goes up the folders to the nearest not-found.tsx, the way an error goes up to the nearest error.tsx. In the order's folder, the docs place not-found.tsx inside the loading state and the error screen: the layout is outside all three, so it stays. Move the file, and guess which screen Chrome shows for /orders/9999:

1import Link from "next/link";2 3export default function OrderNotFound() {4  return (5    <main>6      <h1>Order not found</h1>7      <p>Check the number on your receipt.</p>8      <Link href="/">Back to the shop</Link>9    </main>10  );11}

With the file in the order's folder, its own screen shows. With only app/not-found.tsx, that one shows: Not on the menu. With none at all, Next.js uses its own, still inside the root layout: 404, This page could not be found., and the tab's title changes to 404: This page could not be found.

app/not-found.tsx has a second job. It also answers addresses that match no route at all, like /oolong, as Project structure showed. Pick Only in app and open the Network tab: /oolong answered 404, and its HTML already holds Not on the menu. Next.js knew before it rendered anything that no route matched. Next.js also has an experimental global-not-found.tsx, for apps with no single root layout; the docs explain it.

forbidden(): signed in, but not allowed

Orders are private. Asha may see her order, 1042, but not Ben's, 1043. When the shop knows who the visitor is, and that visitor may not see the page, call forbidden(). Next.js shows forbidden.tsx. Its status code, when it can send one, is 403 Forbidden.

forbidden() and unauthorized() are still experimental in Next.js 16.4.3. To use them, turn them on in next.config.ts, the file Project structure introduced:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  cacheComponents: true,
  partialPrefetching: true,
  experimental: {
    authInterrupts: true,
  },
};

export default nextConfig;

Lines 7 to 9 are the new part: experimental: { authInterrupts: true }. Lines 5 and 6 were already there, as create-next-app writes them. Here is the shop with sign-in added. Click through its files, then read the Steps tab:

1import { forbidden, notFound, unauthorized } from "next/navigation";2import { getCustomer, getOrder } from "../../_data/orders";3 4export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {5  const customer = await getCustomer();6  if (!customer) unauthorized();7  const { id } = await params;8  const order = await getOrder(id);9  if (!order) notFound();10  if (order.customer !== customer) forbidden();11  return (12    <main>13      <h1>Order {order.id}</h1>14      <p>15        {order.boxes} boxes of {order.tea}16      </p>17    </main>18  );19}

In app/_data/orders.ts, line 15 reads the visitor's name from a cookie called customer: a stand-in for real sign-in, which Authentication teaches. Each order has a customer, on lines 4 and 5. In app/orders/[id]/page.tsx, line 10 compares them: if the order isn't this customer's, forbidden() stops the page. Step 5, signed in as Asha, opened /orders/1043 and showed app/forbidden.tsx: This order is not yours. Step 4 opened her own order, 1042, which showed as usual.

Without the setting, the function doesn't work. Here is the same shop with the next.config.ts that create-next-app writes, asked for /orders/1043 as Asha. Open the Terminal tab and read what next start printed:

1import { forbidden, notFound, unauthorized } from "next/navigation";2import { getCustomer, getOrder } from "../../_data/orders";3 4export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {5  const customer = await getCustomer();6  if (!customer) unauthorized();7  const { id } = await params;8  const order = await getOrder(id);9  if (!order) notFound();10  if (order.customer !== customer) forbidden();11  return (12    <main>13      <h1>Order {order.id}</h1>14      <p>15        {order.boxes} boxes of {order.tea}16      </p>17    </main>18  );19}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (5/5)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├   /orders/[id]│ └ ◐ /orders/[id]└ ○ /sign-in ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Ready⨯ Error: `forbidden()` is experimental and only allowed to be enabled when `experimental.authInterrupts` is enabled.    at d (.next/server/chunks/ssr/_0wxhkcy8ti8qe._.js:1:654)    at h (.next/server/chunks/ssr/_0wxhkcy8ti8qe._.js:1:456) {  digest: '1905272039'}⨯ Error: `forbidden()` is experimental and only allowed to be enabled when `experimental.authInterrupts` is enabled.    at d (.next/server/chunks/ssr/_0wxhkcy8ti8qe._.js:1:654)    at h (.next/server/chunks/ssr/_0wxhkcy8ti8qe._.js:1:456) {  digest: '2320678624'}

The build passed, but the request failed: Error: `forbidden()` is experimental and only allowed to be enabled when `experimental.authInterrupts` is enabled. An ordinary error: like any thrown error, it goes to the nearest error screen, not to forbidden.tsx. With the setting on, the build of the example above lists it: Experiments (use with caution): and ✓ authInterrupts.

unauthorized(): sign in first

forbidden() needs to know who the visitor is. Before that, there's an earlier question: is anyone signed in at all? If not, call unauthorized(). Next.js shows unauthorized.tsx, and its status code, when it can send one, is 401 Unauthorized: sign in, and you might be let in. The same example, from its first step:

1import { forbidden, notFound, unauthorized } from "next/navigation";2import { getCustomer, getOrder } from "../../_data/orders";3 4export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {5  const customer = await getCustomer();6  if (!customer) unauthorized();7  const { id } = await params;8  const order = await getOrder(id);9  if (!order) notFound();10  if (order.customer !== customer) forbidden();11  return (12    <main>13      <h1>Order {order.id}</h1>14      <p>15        {order.boxes} boxes of {order.tea}16      </p>17    </main>18  );19}

• Step 1, open /orders/1042: nobody is signed in, so getCustomer() on line 5 finds no cookie, and line 6 calls unauthorized(). Chrome shows app/unauthorized.tsx: Sign in to see your order and a Sign in link.
• Steps 2 and 3, sign in: the link goes to /sign-in, and the button there stores the cookie.
• Step 4, open /orders/1042 again: now line 5 finds "asha", and Asha sees her order.

"use client";

import { useState } from "react";

// A pretend sign-in: it only stores the name in a cookie. A real shop checks a password first.
export default function SignInButton() {
  const [signedIn, setSignedIn] = useState(false);

  function signIn() {
    document.cookie = "customer=asha; path=/";
    setSignedIn(true);
  }

  return signedIn ? <p>Signed in as Asha</p> : <button onClick={signIn}>Sign in as Asha</button>;
}

Line 10 sets the cookie customer=asha with document.cookie, line 11 remembers that the visitor signed in, and line 14 shows Signed in as Asha. A real shop checks a password first, as the comment on line 5 says. The Steps tab also lists React error #419 twice in step 2: React's note that the server couldn't finish the order's part of the first HTML, so the browser drew it.

Put together, the order page asks three questions, in order. The first "no" stops it:

The order of the checks matters. Line 6 comes first, so a visitor who isn't signed in can't learn whether order 9999 exists. The docs add one limit: forbidden() and unauthorized() can't be called in the root layout.

Status codes and search engines

A status code is the number at the start of every response: 200 means here is the page, 404 not found, 403 forbidden, 401 sign in first. Search engines read it: a page that answers 404 is dropped from their results. So why did every order page answer 200, even the ones that stopped?

Because of streaming, from Loading UI. The status code is sent first, together with the first part of the page. The order page waits for params, so Next.js sent the layout and Loading your order… at once, with 200. When the page ran and called unauthorized(), the status had already left. Next.js can't take it back. What it can still do is add the tag <meta name="robots" content="noindex">, which tells search engines not to keep the page in their results. React then draws unauthorized.tsx in the browser, which is why the recorded HTML only held the loading state.

A check that runs before anything is sent gets the real status. One place is the build: a page that calls notFound() while next build makes it. The shop's sale page only exists while a sale is on:

import { notFound } from "next/navigation";
import { getSale } from "../_data/sale";

export default async function SalePage() {
  const sale = await getSale();
  if (!sale) notFound();
  return (
    <main>
      <h1>{sale.title}</h1>
      <p>{sale.discount}% off every tea</p>
    </main>
  );
}

Line 5 asks for the sale, and right now there's none, so line 6 calls notFound(). This page reads nothing from the request, so it runs during the build. Compare both cases:

1import { notFound } from "next/navigation";2import { getSale } from "../_data/sale";3 4export default async function SalePage() {5  const sale = await getSale();6  if (!sale) notFound();7  return (8    <main>9      <h1>{sale.title}</h1>10      <p>{sale.discount}% off every tea</p>11    </main>12  );13}

<!DOCTYPE html>
<html id="__next_error__">
  <head>
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/3l_qmp-61z4yc.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/3oh00mkbkq8u6.js" async=""></script>
    <meta name="robots" content="noindex">
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

/sale answered 404, with the noindex tag, and the Terminal tab lists it as ○ /sale: the build saved the not-found result, and every visitor gets it. Its HTML is an almost empty document with the noindex tag; in Chrome, React drew Not on the menu from it. The order page answered 200, with the noindex tag. Each row is one way a page can be missing, and what the response says:

Is a 200 with noindex a problem? The docs say some search engines call it a "soft 404", and the noindex tag keeps it out of their results. For private pages like orders, search engines can't see them anyway: they never sign in. When a team still needs the real 401, 403 or 404 for each request, the docs suggest running the check before the page renders, in proxy.ts, which the proxy.ts lesson teaches. And Dynamic routes showed a third case: a tea page whose slug the build didn't list answered 200 the first time and 404 after that, once Next.js had saved the result.

Choosing the right one

The three functions answer three different problems. Each row is one of them, the file that shows, and the status code it stands for:

The shop's order pages, ready to ship, have one of each file: not-found.tsx in the order's folder, because its message is about orders, and forbidden.tsx and unauthorized.tsx in app, for every page that checks who's asking:

app/
  _data/
    orders.ts
  orders/
    [id]/
      loading.tsx
      not-found.tsx
      page.tsx
  sign-in/
    page.tsx
    sign-in-button.tsx
  forbidden.tsx
  layout.tsx
  page.tsx
  unauthorized.tsx
next.config.ts

Now sort these visits: which function should the page call?

Common mix-ups

• "notFound() always sends a 404." Only before the response starts. The recorded /orders/9999 answered 200, with a noindex tag.
• "You have to write return notFound()." No. It throws, so nothing after it runs.
• "error.tsx catches notFound()." No. Next.js passes its own errors on to the right file.
• "forbidden() works like notFound() in every project." No, not in 16.4.3. It needs experimental.authInterrupts, or it throws an ordinary error.
• "401 and 403 mean the same thing." No. 401: sign in first. 403: signed in, and still not allowed.
• "Without a not-found.tsx in the folder, the visitor gets a blank page." No. The next one up shows, or Next.js's own.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

app/
  _data/
    orders.ts
  orders/
    [id]/
      loading.tsx
      not-found.tsx
      page.tsx
  layout.tsx
  page.tsx

import { forbidden, notFound, unauthorized } from "next/navigation";
import { getCustomer, getOrder } from "../../_data/orders";

export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {
  const customer = await getCustomer();
  if (!customer) unauthorized();
  const { id } = await params;
  const order = await getOrder(id);
  if (!order) notFound();
  if (order.customer !== customer) forbidden();
  return (
    <main>
      <h1>Order {order.id}</h1>
      <p>
        {order.boxes} boxes of {order.tea}
      </p>
    </main>
  );
}

import { notFound } from "next/navigation";
import { getOrder } from "../../_data/orders";

export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {
  const { id } = await params;
  const order = await getOrder(id);
  // If no order has this number, show the not-found page
  return (
    <main>
      <h1>Order {order.id}</h1>
      <p>
        {order.boxes} boxes of {order.tea}
      </p>
    </main>
  );
}

import { notFound } from "next/navigation";
import { getOrder } from "../../_data/orders";

export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {
  const { id } = await params;
  const order = await getOrder(id);
  if (!order) notFound();
  return (
    <main>
      <h1>Order {order.id}</h1>
      <p>
        {order.boxes} boxes of {order.tea}
      </p>
    </main>
  );
}

import { forbidden, notFound, unauthorized } from "next/navigation";
import { getCustomer, getOrder } from "../../_data/orders";

export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {
  const customer = await getCustomer();
  if (!customer) unauthorized();
  const { id } = await params;
  const order = await getOrder(id);
  if (!order) notFound();
  if (order.customer !== customer) forbidden();
  return (
    <main>
      <h1>Order {order.id}</h1>
      <p>
        {order.boxes} boxes of {order.tea}
      </p>
    </main>
  );
}

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  cacheComponents: true,
  partialPrefetching: true,
  experimental: {
    authInterrupts: true,
  },
};

export default nextConfig;

import { forbidden, notFound, unauthorized } from "next/navigation";
import { getCustomer, getOrder } from "../../_data/orders";

export default async function OrderPage({ params }: PageProps<"/orders/[id]">) {
  const customer = await getCustomer();
  if (!customer) unauthorized();
  const { id } = await params;
  const order = await getOrder(id);
  if (!order) notFound();
  if (order.customer !== customer) forbidden();
  return (
    <main>
      <h1>Order {order.id}</h1>
      <p>
        {order.boxes} boxes of {order.tea}
      </p>
    </main>
  );
}

import { notFound } from "next/navigation";
import { getSale } from "../_data/sale";

export default async function SalePage() {
  const sale = await getSale();
  if (!sale) notFound();
  return (
    <main>
      <h1>{sale.title}</h1>
      <p>{sale.discount}% off every tea</p>
    </main>
  );
}

Check your understanding

Key takeaways

• notFound() stops a page whose thing doesn't exist, and Next.js shows the nearest not-found.tsx, inside the layouts. It throws, so nothing after it runs.
• Without a not-found.tsx in the folder, the next one up shows; app/not-found.tsx also answers addresses with no route. With none, Next.js uses its own.
• unauthorized() means sign in first (401); forbidden() means signed in, and still not allowed (403). They show unauthorized.tsx and forbidden.tsx.
• In Next.js 16.4.3, forbidden() and unauthorized() are experimental: turn on experimental.authInterrupts in next.config.ts.
• The status code goes out with the first part of the response. A check during the build gets the real status; a check after the first part was streamed keeps 200 and gets a noindex tag.

Coming next: Redirects. It shows every way to send a visitor somewhere else, with redirect(), in next.config.ts and in proxy.ts.