Intense-Visions Next.js Error Boundaries
Handle runtime errors and missing routes gracefully with error.tsx and not-found.tsx
When to Use
- Displaying a user-friendly error UI when a route segment throws during rendering or data fetching
- Providing a recovery mechanism (retry button) without reloading the entire page
- Customizing the 404 page for missing routes or resources
- Isolating errors so one failing segment does not crash the entire application
- Handling global uncaught errors at the root layout level
Instructions
- Create
error.tsxin a route segment directory to catch errors thrown by that segment'spage.tsxor its Server Components. - Mark
error.tsxas a Client Component with'use client'— error boundaries must be Client Components. - Accept
error: Error & { digest?: string }andreset: () => voidprops —digestis a server-side error ID for log correlation;resetre-renders the segment. - Create
global-error.tsxinapp/to catch errors from the root layout — it replaces the entire layout including<html>and<body>, so include them. - Call
notFound()fromnext/navigationinside any Server Component to trigger the nearestnot-found.tsx. - Create
not-found.tsxinapp/for a global 404 page, or in any route segment for segment-specific 404s. - Nest
error.tsxcloser to the throwing component to limit the error UI scope — a top-levelerror.tsxcatches all descendant errors but shows a large recovery region. - Log the
error.digestto your error monitoring service (Sentry, Datadog) to correlate client-visible errors with server logs.
// app/dashboard/error.tsx — segment error boundary
'use client';
export default function DashboardError({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<div role="alert">
<h2>Something went wrong loading the dashboard</h2>
<p className="text-sm text-gray-500">Error ID: {error.digest}</p>
<button again</button>
</div>
);
}
// app/posts/[slug]/not-found.tsx — segment-specific 404
export default function PostNotFound() {
return (
<div>
<h1>Post not found</h1>
<p>The post you are looking for does not exist or has been removed.</p>
</div>
);
}
// app/posts/[slug]/page.tsx — triggering not-found
import { notFound } from 'next/navigation';
export default async function PostPage({ params }: { params: { slug: string } }) {
const post = await fetchPost(params.slug);
if (!post) notFound(); // triggers not-found.tsx
return <article>{post.content}</article>;
}
Details
Next.js automatically wraps each route segment in a React error boundary when error.tsx exists. The error boundary catches errors thrown during rendering, in event handlers, or in asynchronous data fetching within that segment.
Error propagation: Errors bubble up through React's component tree until they reach an error boundary. Without error.tsx, unhandled errors propagate to the root and show the default Next.js error page (development) or a blank white screen (production).
reset() function: Calling reset() attempts to re-render the content within the error boundary. If the underlying error was transient (e.g., a network blip), the reset succeeds. If the error persists, the error boundary catches it again. Combine with a retry counter to avoid infinite loops.
global-error.tsx vs error.tsx: error.tsx in app/ catches errors from the root page but not from the root layout. global-error.tsx catches errors from the root layout itself (e.g., a broken navigation component). global-error.tsx must render <html> and <body> because it replaces the entire document.
Server vs client error messages: In production, error messages thrown on the server are not forwarded to the client to avoid leaking sensitive details. Only the digest ID is passed. In development, full error details are shown. This asymmetry is intentional — use the digest to look up errors in server logs.
not-found.tsx placement: A not-found.tsx in a segment catches notFound() calls from that segment only. A not-found.tsx in app/ serves as the global 404 fallback for all routes.
Source
https://nextjs.org/docs/app/building-your-application/routing/error-handling
Process
- Read the instructions and examples in this document.
- Apply the patterns to your implementation, adapting to your specific context.
- Verify your implementation against the details and edge cases listed above.
Harness Integration
- Type: knowledge — this skill is a reference document, not a procedural workflow.
- No tools or state — consumed as context by other skills and agents.
Success Criteria
- The patterns described in this document are applied correctly in the implementation.
- Edge cases and anti-patterns listed in this document are avoided.