error.tsx and not-found.tsx are Next.js file conventions that contain a route's failure to that route instead of letting it crash the whole app.

Think of a building's fire doors: a fire in one office closes behind its own door and never spreads to the rest of the floor. Production apps fail — database connections drop, external APIs return 500s, unexpected data causes JavaScript errors. The question isn't whether errors will happen, it's whether they crash your entire app or stay contained to the section that broke.

error.tsx — Catching Runtime Errors

Create an error.tsx file alongside any page.tsx to catch errors thrown during rendering or data fetching in that route:

tsx

// src/app/error.tsx — global error boundary
"use client";   // error.tsx must be a Client Component

import { useEffect } from "react";

interface ErrorProps {
    error: Error & { digest?: string };
    reset: () => void;
}

export default function GlobalError({ error, reset }: ErrorProps) {
    useEffect(() => {
        // Log to an error reporting service
        console.error("Unhandled error:", error);
    }, [error]);
    
    return (
        <main className="min-h-screen flex items-center justify-center px-4">
            <div className="max-w-md text-center">
                <div className="w-16 h-16 bg-red-100 rounded-full flex items-center justify-center mx-auto mb-6">
                    <svg className="w-8 h-8 text-red-600" fill="none" viewBox="0 0 24 24" stroke="currentColor">
                        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
                    </svg>
                </div>
                <h1 className="text-2xl font-bold text-gray-900">Something went wrong</h1>
                <p className="text-gray-500 mt-2">
                    {process.env.NODE_ENV === "development" 
                        ? error.message 
                        : "An unexpected error occurred. We've been notified."}
                </p>
                {error.digest && (
                    <p className="text-xs text-gray-400 mt-1">Error ID: {error.digest}</p>
                )}
                <div className="flex gap-3 justify-center mt-6">
                    <button
                        onClick={reset}
                        className="bg-blue-600 hover:bg-blue-700 text-white font-semibold px-5 py-2.5 rounded-lg transition-colors"
                    >
                        Try again
                    </button>
                    <a
                        href="/"
                        className="border border-gray-300 text-gray-700 hover:bg-gray-50 font-semibold px-5 py-2.5 rounded-lg transition-colors"
                    >
                        Go home
                    </a>
                </div>
            </div>
        </main>
    );
}

The reset function re-renders the error boundary and retries the failed component. The error.digest is a hash of the error for server-side log correlation.

Scoped Error Boundaries

Put error.tsx inside a specific folder to limit the error boundary to that section:

code

src/app/
├── error.tsx              → Catches errors anywhere in the app
├── dashboard/
│   ├── error.tsx          → Only catches errors in /dashboard/**
│   ├── page.tsx
│   └── analytics/
│       ├── error.tsx      → Only catches errors in /dashboard/analytics
│       └── page.tsx

The analytics error boundary doesn't crash the whole dashboard. An analytics error shows a friendly error UI just for that section while the rest of the dashboard works normally.

not-found.tsx — Handling Missing Resources

When a page calls notFound(), Next.js renders the nearest not-found.tsx:

tsx

// src/app/not-found.tsx — shown for any 404
import Link from "next/link";

export default function NotFound() {
    return (
        <main className="min-h-screen flex items-center justify-center px-4">
            <div className="max-w-md text-center">
                <h1 className="text-9xl font-black text-gray-100 select-none">404</h1>
                <div className="-mt-8">
                    <h2 className="text-3xl font-bold text-gray-900">Page not found</h2>
                    <p className="text-gray-500 mt-3">
                        The page you're looking for doesn't exist or has been moved.
                    </p>
                    <div className="flex gap-3 justify-center mt-8">
                        <Link
                            href="/"
                            className="bg-blue-600 hover:bg-blue-700 text-white font-semibold px-5 py-2.5 rounded-lg transition-colors"
                        >
                            Go home
                        </Link>
                        <Link
                            href="/courses"
                            className="border border-gray-300 text-gray-700 hover:bg-gray-50 font-semibold px-5 py-2.5 rounded-lg transition-colors"
                        >
                            Browse courses
                        </Link>
                    </div>
                </div>
            </div>
        </main>
    );
}

Trigger it from any server component or API route:

tsx

// src/app/courses/[slug]/page.tsx
import { notFound } from "next/navigation";

export default async function CoursePage({ params }: { params: { slug: string } }) {
    const course = await getCourse(params.slug);
    
    if (!course) {
        notFound();   // renders not-found.tsx with 404 status
    }
    
    return <CourseDetail course={course} />;
}

Scoped not-found.tsx files work just like scoped error.tsx:

tsx

// src/app/courses/not-found.tsx — specific to /courses/**
export default function CourseNotFound() {
    return (
        <div className="text-center py-16">
            <h2 className="text-2xl font-bold">Course not found</h2>
            <p className="text-gray-500 mt-2">
                This course doesn't exist or has been removed.
            </p>
            <Link href="/courses" className="mt-6 inline-block text-blue-600 hover:underline">
                Browse all courses
            </Link>
        </div>
    );
}

Triggering Errors vs Not Found

tsx

// Use notFound() for "this resource doesn't exist"
// → 404 status, renders not-found.tsx
if (!course) notFound();

// Throw an error for unexpected failures
// → 500 status, renders error.tsx
if (!db) throw new Error("Database connection failed");

// Use redirect() for auth failures
// → 307 redirect, no error boundary
if (!user) redirect("/login");

Error Handling in API Routes

// src/app/api/courses/[id]/route.ts
import { NextRequest, NextResponse } from "next/server";
import { db } from "@/lib/db";

export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
    try {
        const course = await db.course.findUnique({ where: { id: params.id } });
        
        if (!course) {
            return NextResponse.json(
                { error: "Course not found" },
                { status: 404 }
            );
        }
        
        return NextResponse.json(course);
    } catch (error) {
        console.error("Failed to fetch course:", error);
        return NextResponse.json(
            { error: "Internal server error" },
            { status: 500 }
        );
    }
}

Global Error for Layout Errors

If the root layout.tsx itself throws, you need a special global-error.tsx (it replaces the entire <html> in that case):

tsx

// src/app/global-error.tsx
"use client";

export default function GlobalError({ error, reset }: { error: Error; reset: () => void }) {
    return (
        <html>
            <body>
                <div className="min-h-screen flex items-center justify-center">
                    <div className="text-center">
                        <h1>Something went catastrophically wrong</h1>
                        <button onClick={reset}>Try again</button>
                    </div>
                </div>
            </body>
        </html>
    );
}

global-error.tsx is a last resort — layout errors are rare. The standard error.tsx handles page-level errors in the vast majority of cases.

Next lesson: Route groups and parallel routes — advanced App Router patterns for complex navigation.

💬 DiscussionPowered by GitHub Discussions

📱

Get this course's notes on Telegram!

Free cheat sheets, summaries & practice exercises

Get Notes Free →

14 minLesson 16 of 33

Course Contents(33 lessons)

▾

React Core Concepts

React 19 Fundamentals & JSX14 min

Components: Thinking in React18 min

Props & Component Composition16 min

useState: State Management20 min

useEffect: Side Effects Mastery22 min

Event Handling & Synthetic Events14 min

Advanced React Patterns

Context API & useContext20 min

useReducer for Complex State18 min

useMemo & useCallback: Performance16 min

useRef & Forwarding Refs16 min

Custom Hooks: Reusable Logic22 min

React.memo & Avoiding Re-renders18 min

Next.js App Router

Next.js 15 Architecture Overview16 min

Layouts & Nested Layouts18 min

Loading UI & Suspense16 min

Error Boundaries & not-found14 min

Route Groups & Parallel Routes18 min

Server & Client Components

The Server Component Mental Model20 min

When to Use Client Components16 min

Server Actions & Form Handling22 min

Streaming & Suspense Boundaries18 min

Data Fetching & Caching

Next.js Caching Strategies Explained24 min

SWR & React Query for Client Fetching22 min

Optimistic Updates & Mutations18 min

Authentication

Auth Overview: Sessions vs JWT vs OAuth18 min

NextAuth.js v5 Setup26 min

Protected Routes & Middleware20 min

Styling & UI

Tailwind CSS in Next.js16 min

Shadcn UI Component Library20 min

Dark Mode Implementation14 min

Testing & Deployment

Testing React with Vitest & Testing Library26 min

Deploy to Vercel: Production Setup18 min

Performance Optimization & Core Web Vitals22 min

Next.js App Router

Error Boundaries & not-found