Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Show a 404 page for unknown URLs in React Router

ErrorBlank page on a URL that no route matches

Short answer

React Router only renders a page when a route matches the URL. To show a 404 page for everything else, add a route whose path is a bare star, as the last sibling. In framework mode, register route("*", file) and throw a 404 Response from its loader so the status code is real as well.

  • Applies to React Router 7, React 19, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which routing mode the app uses. The file that defines your routes tells you, and each mode adds its catch-all in a different place.

    grep -rn -E "createBrowserRouter|<Routes|BrowserRouter|routes.ts" src app --include=*.tsx --include=*.jsx --include=*.ts --include=*.js
  2. 2Match what you see, then jump to its fix

    1. 1Unknown URLs render nothing, or the default error screen, and the route list has no path ending in a starNo catch-all route exists in a JSX or object route treeFix
    2. 2The app uses app/routes.ts and an unknown URL does not show your own pageFramework mode: routes.ts has no star routeFix

What does the error look like?

  • Blank page on a URL that no route matches
  • An unknown URL shows the router default error screen instead of your own page

Cause 1 of 2

No catch-all route exists in a JSX or object route tree

1Check

Open the file with your Routes or createBrowserRouter list. A route path that ends with /* matches any text after the slash, including more slashes (the docs call this a splat). A bare star is that rule with nothing in front of it.

grep -rn 'path=' src | head -30

2Fix

Add one route with a bare star as its path and give it a NotFound component. Put it in the same list as the other top-level routes. Specific paths such as about still win over the star.

import { BrowserRouter, Routes, Route } from "react-router";

<BrowserRouter>
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="about" element={<About />} />
    <Route path="*" element={<NotFound />} />
  </Routes>
</BrowserRouter>

3Verify

Start the dev server and open a URL that does not exist, such as /no-such-page. The NotFound component renders and /about still shows About.

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:5173/about

Confirmed by reactrouter.com

Did this fix it?

Cause 2 of 2

Framework mode: routes.ts has no star route

1Check

Open app/routes.ts. In framework mode the catch-all is declared there with the pattern *, pointing at a route module file.

cat app/routes.ts

2Fix

Add a route with the pattern * as the last entry, then create that file. Throw a Response with status 404 from its loader, so browsers and crawlers get a real 404 status and not just a page that looks like one.

// app/routes.ts
route("*", "./catchall.tsx"),

// app/catchall.tsx
export function loader() {
  throw new Response("Page not found", { status: 404 });
}

3Verify

Request an unknown URL and read the status line of the response.

curl -I http://localhost:5173/no-such-page

Confirmed by reactrouter.com

Did this fix it?

How do I stop it coming back?

  • Keep the star route as the only route with that path, so it is easy to find.
  • In framework mode, return a 404 status from the loader, so search engines do not index the not-found page as a normal page.
  • Add an unknown URL to your smoke test or end-to-end test, next to the happy-path routes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.