throw or return Error Response from loaders?

[alicerocheman]

Hi,

I'm currently working on an app with react-router v7 as a framework.

So far, my loaders check the validity of certain routes, and throw a 404 Response if the route makes no sense, or return a redirect.
I've done this because I've seen examples with throwing.
I have not found anything about this in the docs (maybe it should be added there)

I'm wondering whether throwing the 404 response is a good practice, or if it should just be returned.

I've tried both quickly and have not seen a difference on the user end

There is a difference in testing complexity, which would be much simpler if i simply returned responses instead of throwing, which I'm struggling with now, trying to test a complex loader.

[gustavopch]

Throwing doesn't affect the return type of the function in TS, so the type of loaderData/actionData in the component is simpler, which is why I prefer to throw anything that's not meant to be handled by the component.

[DucMinhNe]

Short version: for a 404 (or any "stop rendering and show an error UI" case) you want to throw, not return. For a redirect, either works, but throw is the idiomatic choice. The reason you don't see a difference on the user end for redirects is that React Router follows a redirect() Response whether you throw it or return it — but a 404 behaves very differently between the two.

Why throwing is correct for the 404 case:

Throwing short-circuits the render. When a loader throws, React Router stops rendering that route's component and renders the nearest ErrorBoundary instead. From the route module docs: "When other route module APIs throw, the route module ErrorBoundary will render instead of the route component." That's exactly what you want for a not-found page.

The canonical pattern uses data() so you get a status code plus a body, and you read it back with isRouteErrorResponse:

import { data } from "react-router";

export async function loader({ params }: Route.LoaderArgs) {
  const record = await db.getRecord(params.id);
  if (!record) {
    throw data("Record Not Found", { status: 404 });
  }
  return record; // <- if you reach here, `record` is guaranteed defined
}

import { isRouteErrorResponse, useRouteError } from "react-router";

export function ErrorBoundary() {
  const error = useRouteError();
  if (isRouteErrorResponse(error) && error.status === 404) {
    return <h1>Not found</h1>;
  }
  throw error; // let it bubble to a parent boundary
}

If you return the 404 Response instead, you don't get this behavior — for a route with a component, the return value becomes your loaderData, your route component renders as normal, and nothing routes to the error UI. So returning a 404 doesn't actually do what you want; it likely only seemed to work in your testing because you weren't asserting on what rendered.

There's also a TypeScript benefit for the 404 / data() case specifically: throwing doesn't widen the loader's return type. Because the throw data(...) path never returns, TS narrows record to non-null after the guard, and loaderData in your component is just your happy-path type. If you return a data(...)/Response error branch instead, every consumer of loaderData has to account for the union — exactly the kind of noise you want to avoid. (Note: this widening argument does not apply to redirect() — React Router now excludes redirect() Responses from the inferred loaderData type whether you throw or return them, see #12527. So for redirects the type stays clean either way; it's data()/raw error Responses where returning widens the type.)

For redirects specifically:

import { redirect } from "react-router";
if (!isLoggedIn(request)) throw redirect("/login");

The docs show throw redirect("/login"), and that's what I'd use. Returning it also redirects (RR follows redirect-status Responses either way), so the practical difference here is mostly stylistic — throwing keeps it as a clean control-flow short-circuit, which is why it reads as the idiomatic choice.

On your testing pain — this is the legitimate downside, and the fix is to test for the throw rather than restructure your app around return values. A thrown Response is just a value you can assert on:

import { isRouteErrorResponse } from "react-router";

it("404s for missing records", async () => {
  try {
    await loader({ params: { id: "nope" } } as any);
    throw new Error("expected loader to throw");
  } catch (thrown) {
    // thrown is a Response
    expect(isRouteErrorResponse(thrown) || thrown instanceof Response).toBe(true);
    expect((thrown as Response).status).toBe(404);
  }
});

await expect(loader(args)).rejects... works too if you're on Vitest/Jest. So you keep the correct runtime behavior and the clean types, and your test just expects a rejection with a Response instead of an assertion on a returned value.

Docs for reference:

• Error boundary how-to (the 404 + useRouteError + isRouteErrorResponse pattern): https://reactrouter.com/how-to/error-boundary
• Setting status codes (throw data(null, { status: 404 })): https://reactrouter.com/how-to/status
• redirect: https://reactrouter.com/api/utils/redirect
• data: https://reactrouter.com/api/utils/data