Suggest an edit

Improve this article

Refine the answer for “What does not-found.tsx do in Next.js?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

`not-found.tsx` is a **404 page for a specific routing segment** in the App Router.
It fires when Next.js **explicitly understands that the page was not found**.

Simply put:

> `not-found.tsx` **= "this resource does not exist"**

---

## What `not-found.tsx` is

In **Next.js**, the `not-found.tsx` file:

- is shown in a **404 scenario**
- can be **global or per-segment**
- **is NOT an error boundary**
- is used for **expected "not found" situations**

## Where it can live

```txt
app/
 ├─ not-found.tsx        # global 404
 ├─ blog/
 │   └─ not-found.tsx   # only for /blog/*
 └─ page.tsx
```

### Priority

1. a segment's `not-found.tsx`
2. the global `app/not-found.tsx`
3. Next's default 404

---

## How it gets called

### 1. Explicitly via `notFound()`

```ts
import { notFound } from "next/navigation";

export default async function Page({ params }) {
  const post = await getPost(params.id);

if (!post) {
    notFound(); // ← here
  }

return <Post post={post} />;
}
```

**This is the main and correct way**

---

### 2. An invalid dynamic route

```txt
app/users/[id]/page.tsx
```

If:

- `/users/999`
- the user doesn't exist
- you called `notFound()`

→ `not-found.tsx` will be rendered

---

## When it does NOT fire

- a runtime error
- an exception
- throw new Error

For that, use:

- `error.tsx`
- `global-error.tsx`

---

## `not-found.tsx` vs `error.tsx`

| | not-found.tsx | error.tsx |
| --- | --- | --- |
| Type | expected scenario | error |
| HTTP status | **404** | 500 |
| Needs `use client` | no | yes |
| Has `reset()` | no | yes |
| For business logic | yes | no |

---

## Minimal example

```tsx
export default function NotFound() {
  return (
    <div>
      <h1>404</h1>
      <p>Page not found</p>
    </div>
  );
}
```

**A Server Component**, without `use client`.

---

## Important nuances

### SEO

- returns **HTTP 404**
- search engines understand everything correctly

### Layouts

- `not-found.tsx` **renders inside the layout**
- `global-error.tsx` does not

### Metadata

- you can set `metadata` for the 404 page
- useful for SEO and UX

Markdown · drag & drop images · ⌘B / ⌘I shortcuts347 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.