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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add a 404 Page to a SolidJS App (SolidJS)
- Add a 404 Page to a Vue Router App (Vue)
- Add a Not Found Page to an Angular App (Angular)