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
});
createRootRouteis the root route insrc/routes/__root.tsx, which wraps every page.notFoundComponentis the component TanStack Start shows when no page matches the address.<NotFound component>is a React component that returns your 404 page.
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:
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 page appears inside the root route, so the header stays, and the warning doesn’t appear any more.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Naming a file 404.tsx | You get an ordinary page at the address /404 | Use notFoundComponent on the root route |
| Leaving out the link back | Visitors on the 404 page have nowhere to go | Link to the home page, or to the pages visitors want most |
Troubleshooting
| Problem | Fix |
|---|---|
The terminal warns A notFoundError was encountered on the route with ID "__root__", but a notFoundComponent option was not configured | Add 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
- Not Found Errors in the TanStack Router docs
- createRootRoute reference
- Production Checklist for TanStack Start
Related
- TanStack Start Tutorial — Part 3: Pages and Links: File-Based Routing
- TanStack Start Tutorial for Beginners, every part of the series
TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.
