Not Found (404) Handling

When a document isn’t found on a web server, it should send a 404 status code. This indicates to machines that the document is not there: search engines won’t index it, CDNs won’t cache it, etc. Most SPAs today just serve everything as 200 whether the page exists or not, but for you that stops today!

There are two primary cases where a Remix site should send a 404:

  • The URL doesn’t match any routes in the app
  • Your loader didn’t find any data

The first case is already handled by Remix, you don’t have to throw a response yourself. It knows your routes so it knows if nothing matched (consider using a Splat Route to handle this case). The second case is up to you, but it’s really easy.

How to Send a 404

As soon as you know you don’t have what the user is looking for you should throw a response.

  1. export async function loader({ params }: LoaderArgs) {
  2.   const page = await db.page.findOne({
  3.     where: { slug: params.slug },
  4.   });
  6.   if (!page) {
  7.     throw new Response(null, {
  8.       status: 404,
  9.       statusText: "Not Found",
  10.     });
  11.   }
  13.   return json(page);
  14. }

Remix will catch the response and send your app down the Catch Boundary path. It’s actually exactly like Remix’s automatic error handling, but instead of exporting an ErrorBoundary, you export a CatchBoundary.

What’s nice about throwing a response is that code in your loader stops executing. The rest of your code doesn’t have to deal with the chance that the page is defined or not (this is especially handy for TypeScript).

Throwing also ensures that your route component doesn’t render if the loader wasn’t successful. Your route components only have to consider the “happy path”. They don’t need pending states, error states, or in our case here, not-found states.

Root Catch Boundary

You probably already have one at the root of your app. This will handle all thrown responses that weren’t handled in a nested route (more on that in a sec). Here’s a sample:

  1. export function CatchBoundary() {
  2.   const caught = useCatch();
  3.   return (
  4.     <html>
  5.       <head>
  6.         <title>Oops!</title>
  7.         <Meta />
  8.         <Links />
  9.       </head>
  10.       <body>
  11.         <h1>
  12.           {caught.status} {caught.statusText}
  13.         </h1>
  14.         <Scripts />
  15.       </body>
  16.     </html>
  17.   );
  18. }

Nested Catch Boundaries

Just like errors, nested routes can export their own catch boundary to handle the 404 UI without taking down all of the parent layouts around it, and add some nice UX touches right in context. Bots are happy, SEO is happy, CDNs are happy, users are happy, and your code stays in context, so it seems like everybody involved is happy with this.

  1. import type { LoaderArgs } from "@remix-run/node"; // or cloudflare/deno
  2. import {
  3.   Form,
  4.   useLoaderData,
  5.   useParams,
  6. } from "@remix-run/react";
  8. export async function loader({ params }: LoaderArgs) {
  9.   const page = await db.page.findOne({
  10.     where: { slug: params.slug },
  11.   });
  13.   if (!page) {
  14.     throw new Response(null, {
  15.       status: 404,
  16.       statusText: "Not Found",
  17.     });
  18.   }
  20.   return json(page);
  21. }
  23. export function CatchBoundary() {
  24.   const params = useParams();
  25.   return (
  26.     <div>
  27.       <h2>We couldn't find that page!</h2>
  28.       <Form action="../create">
  29.         <button
  30.           type="submit"
  31.           name="slug"
  32.           value={params.slug}
  33.         >
  34.           Create {params.slug}?
  35.         </button>
  36.       </Form>
  37.     </div>
  38.   );
  39. }
  41. export default function Page() {
  42.   return <PageView page={useLoaderData<typeof loader>()} />;
  43. }

As you can probably tell, this mechanism isn’t just limited to 404s. You can throw any response from a loader or action to send your app down the catch boundary path. For more information, check out the Catch Boundary docs.