Site icon JD Bots

How to Add a Custom 404 Page in TanStack Start

Card titled A Custom 404 Page, showing a browser at localhost:3000/nope with a large 404 and a Go home button.

A custom 404 page in TanStack Start.

When someone opens an address your TanStack Start app has no page for, the app shows the words “Not Found” and nothing else. This post replaces that with a custom 404 page that keeps your site’s header and links back home.

Syntax

Syntax

export const Route = createRootRoute({
	notFoundComponent: <NotFound component>,
	// the root route’s other options
});

TanStack Router’s Not Found Errors guide describes every option.

Step 1: See the Default Page

Open an address with no page, such as http://localhost:3000/nope:

TanStack Router’s default Not Found page.

The terminal running the dev server warns about it:

Output (the lines that matter)

8:34:16 AM [vite] (client) [console.warn] Warning: A notFoundError was encountered on the route with ID "__root__", but a notFoundComponent option was not configured, nor was a router level defaultNotFoundComponent configured. Consider configuring at least one of these to avoid TanStack Router's overly generic defaultNotFoundComponent (<p>Not Found</p>)

Step 2: Add notFoundComponent to the Root Route

Open src/routes/__root.tsx. The 404 page links back home, so add Link to the import from @tanstack/react-router:

src/routes/__root.tsx (excerpt)

import {
	createRootRoute,
	HeadContent,
	Link,
	Scripts,
} from "@tanstack/react-router";

Then add the notFoundComponent option to createRootRoute, and the NotFound component below it:

src/routes/__root.tsx (excerpt)

	notFoundComponent: NotFound,
	shellComponent: RootDocument,
});

function NotFound() {
	return (
		<main className="mx-auto max-w-2xl p-8">
			<h1 className="text-4xl font-bold">Page not found</h1>
			<p className="mt-4 text-lg">There is no page at this address.</p>
			<Link to="/" className="mt-4 inline-block text-lg underline">
				Go to the home page
			</Link>
		</main>
	);
}

Step 3: Open the Address Again

Open http://localhost:3000/nope again:

The custom 404 page keeps the header and links back home.

The page appears inside the root route, so the header stays, and the warning doesn’t appear any more.

Common Mistakes

MistakeWhat happensDo this instead
Naming a file 404.tsxYou get an ordinary page at the address /404Use notFoundComponent on the root route
Leaving out the link backVisitors on the 404 page have nowhere to goLink to the home page, or to the pages visitors want most

Troubleshooting

ProblemFix
The terminal warns A notFoundError was encountered on the route with ID "__root__", but a notFoundComponent option was not configuredAdd notFoundComponent to the root route, as in Step 2.

FAQ

Does the page return a real 404 status? Yes. For an address with no page, the server answers with the status code 404 together with your page, which tells browsers and search engines that the page doesn’t exist. TanStack Start’s production checklist asks for exactly that.

Can I set the 404 page on the router instead? Yes. createRouter in src/router.tsx takes a defaultNotFoundComponent, which routes without their own notFoundComponent use (Not Found Errors).

How do I show a 404 for a book that doesn’t exist? The page’s loader throws notFound(), and the same notFoundComponent shows. Part 16 of the series covers it.

Conclusion

One option on the root route, notFoundComponent, turns the plain “Not Found” into a page that looks like the rest of your site and helps visitors find their way.

Additional Resources

Related

TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.

Exit mobile version