Skip to main content
0 reactions

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

SyntaxTypeScript
export const Route = createRootRoute({
	notFoundComponent: <NotFound component>,
	// the root route’s other options
});
  • createRootRoute is the root route in src/routes/__root.tsx, which wraps every page.
  • notFoundComponent is 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 (opens in a new tab) describes every option.

Step 1: See the Default Page

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

A browser showing only the words Not Found at the top left of an empty page.
TanStack Router’s default Not Found page.

The terminal running the dev server warns about it:

Output (the lines that matter)Plain text
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)TypeScript
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)TypeScript
	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:

A custom 404 page with the site header, the heading Page not found, the line There is no page at this address, and a link to the home page.
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 (opens in a new tab) 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 (opens in a new tab)).

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

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

0 comments