# Add a Custom 404 Page to a React Router App

Yes. An agent adds a splat route to a React Router app so unknown URLs get a real 404 status and your own page, checks it on the built server and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-not-found-page/react-router/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from the route table, because in React Router's framework mode a 404 is a routing question before it is a design question. In an app generated from remix-run/react-router-templates (the `default` template), `app/routes.ts` has one line of routes, `index("routes/home.tsx")`, and `react-router.config.ts` sets `ssr: true`, so a request for any other path is answered by the server from the `ErrorBoundary` exported in `app/root.tsx`. That boundary already distinguishes a 404 with `isRouteErrorResponse(error)` and `error.status === 404`, but it renders a bare `<h1>404</h1>` inside the root `Layout`, the document title stays whatever the last page set, and the same component is also what a thrown `Error` lands on, so a missing page and a crashed loader look alike.

The change adds a catch-all route and a page of its own. `app/routes.ts` gains `route("*", "routes/not-found.tsx")` after the index, using the `route` helper from `@react-router/dev/routes` beside the `index` import already there. The new module `app/routes/not-found.tsx` exports a `loader` that throws `data(null, { status: 404 })`, so the server response carries a real 404 status and crawlers and uptime checks see one, and its own `ErrorBoundary`, which renders the page: a heading, a sentence, and a `<Link to="/">` back to the home route, styled with the Tailwind classes `app/app.css` already loads. A `meta` export sets the title to `Page not found`. The root boundary is left as it is for everything that is not a missing URL, so a loader that throws elsewhere still gets the root's message and, in development, its stack trace.

Types come from the generator the template already uses. The module imports `Route` from `./+types/not-found`, which `react-router typegen` writes under `.react-router/types`, and `npm run typecheck` runs that generator and then `tsc` with the `rootDirs` entry `tsconfig.json` sets up for it. The agent runs the typecheck, then `npm run build` and `npm run start`, which serves `build/server/index.js` through `react-router-serve`, and checks the result with the server itself: `curl -i` on a made-up path shows `HTTP/1.1 404` and the new markup, `curl -i /` still answers 200 with the welcome page, and a request for a hashed file under `/assets/` that does not exist also gets the 404 page rather than the root boundary. In a browser it loads the missing path with a client-side navigation from the home page too, since a splat route also catches links the app renders to paths that no longer exist.

The agent keeps the change to those two files plus the new module. It does not move the existing `ErrorBoundary` out of `app/root.tsx`, does not add a route for `/404` (the splat is the route), and does not touch `Dockerfile`, which already copies `build/` into the `node:24-alpine` runtime stage, so the image serves the new page without a change. For the `node-custom-server` template, where `server.js` wraps the build in Express, the same splat route applies, because the request still reaches React Router's handler before Express would answer its own 404.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a custom 404 page to this React Router app and open a pull request. Read app/routes.ts, app/root.tsx, app/routes/home.tsx, react-router.config.ts, tsconfig.json and package.json first. Add a splat route with route(\"*\", \"routes/not-found.tsx\") to app/routes.ts. In app/routes/not-found.tsx export a loader that throws data(null, { status: 404 }), a meta export that sets the title to Page not found, and an ErrorBoundary that renders a heading, one sentence and a Link to / using the Tailwind classes the app already uses; import Route from ./+types/not-found. Leave the ErrorBoundary in app/root.tsx as it is. Run npm run typecheck, npm run build and npm run start, then show with curl -i that an unknown path answers 404 with the new page and that / still answers 200. Put the typecheck output and both curl exchanges in the pull request description.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with one new file, `app/routes/not-found.tsx`, and one changed line in `app/routes.ts`. The description shows the `react-router typegen` and `tsc` output from `npm run typecheck`, the `curl -i` exchange for an unknown path with its `404` status line and the page's heading, and the `curl -i /` exchange still answering `200`. The session keeps the build output and the server log, and `GET /o/{org}/p/{project}/sessions/{id}/changes` returns the diff.

A reviewer reads the boundary component for the copy and the classes, checks that the loader throws rather than returns so the status is genuinely 404, and confirms that `app/root.tsx` is unchanged in the diff. On a repository with the templates' own Playwright check, the `build + start` test still passes, because the home page's title and links are untouched.

## Run it on every new React Router repository

Each app a team starts from the template gets the same gap, so start one run per new repository: a handler on your server that receives GitHub's `repository` webhook, or a script that walks `GET /o/{org}/github` for the installation's repositories, calls `POST /o/{org}/sessions` with this body and the repository's URL in `resources`, with a `request_id` per repository so a retry returns the run already started.

Give the key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, signed per Standard Webhooks, with `data.session_url` to read for the pull request. A key runs at most `max_concurrent` sessions at once, 4 by default, and a batch over many React Router apps can be sent without pacing: the sessions past that number come back `202` with `status: "queued"` and start when a slot frees.

## Why run it on Rush?

The part people get wrong with a 404 page in framework mode is the status code: a route that renders a nice page but answers 200 is worse for search and monitoring than the bare default. The agent checks the status with the production server it just built, in its own sandbox, and the `curl -i` lines are on the session, so the pull request shows the 404 rather than asserting it.

The result is a pull request with its own typecheck and a running server behind it, not a snippet to paste. The same request body works on every React Router app a team owns, each in its own sandbox, and the sandbox parks with `node_modules` installed when the turn ends, so a request to change the copy or add a search box to the page is a follow-up on the same session.

## Frequently asked questions

### Why throw from a loader instead of rendering the page as the route component?

Because a route component that renders answers 200. Throwing `data(null, { status: 404 })` makes the server respond with 404 and hands rendering to the nearest `ErrorBoundary`, which is the one in the new module. Search engines, uptime checks and the browser's own handling of the response all see the right status.

### Does it replace the ErrorBoundary in root.tsx?

No. The root boundary keeps handling thrown errors and any error response that is not a missing URL, and still shows a stack trace in development. The splat route's boundary only ever sees the 404 its own loader throws.

### Will it work in SPA mode?

With `ssr: false` there is no server to set a status, so the page renders on the client with whatever status the static host returns for unknown paths. The splat route still shows your page; getting a real 404 status then depends on the host's configuration, which the pull request mentions but does not change.

### Does the generated type file need to be committed?

No. `.react-router/types` is generated by `react-router typegen`, which `npm run typecheck` runs first, and the template's `tsconfig.json` already includes it through `rootDirs`. The pull request adds nothing under that directory.

## More React Router jobs

- [Add Optimistic UI to a React Router Form from a Linear Issue](https://getrush.ai/run/add-optimistic-ui/react-router/)
- [Add Prerendering to a React Router App](https://getrush.ai/run/add-prerendering/react-router/)
- [Add Protected Routes to a React Router App](https://getrush.ai/run/add-protected-routes/react-router/)

## The same job on other stacks

- [Add a 404 Page to a SolidJS App](https://getrush.ai/run/add-not-found-page/solidjs/)
- [Add a 404 Page to a Vue Router App](https://getrush.ai/run/add-not-found-page/vue/)
- [Add a Not Found Page to an Angular App](https://getrush.ai/run/add-not-found-page/angular/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
