Throwing in middleware shouldn’t prevent earlier middleware from unwinding

[richardscarrott]

I'm using React Router as a...

framework

Reproduction

https://stackblitz.com/edit/github-8jsa5pu8?file=app%2Froot.tsx

System Info

System:
    OS: macOS 15.5
    CPU: (10) arm64 Apple M1 Pro
    Memory: 84.63 MB / 32.00 GB
    Shell: 3.7.1 - /opt/homebrew/bin/fish
  Binaries:
    Node: 20.11.0 - ~/.nvm/versions/node/v20.11.0/bin/node
    npm: 10.2.4 - ~/.nvm/versions/node/v20.11.0/bin/npm
    pnpm: 10.11.0 - /opt/homebrew/bin/pnpm
    Watchman: 2025.05.26.00 - /opt/homebrew/bin/watchman
  Browsers:
    Chrome: 137.0.7151.69
    Safari: 18.5
  npmPackages:
    @react-router/dev: ^7.5.3 => 7.6.2
    @react-router/node: ^7.5.3 => 7.6.2
    @react-router/serve: ^7.5.3 => 7.6.2
    react-router: ^7.5.3 => 7.6.2
    vite: ^6.3.3 => 6.3.5

Used Package Manager

npm

Expected Behavior

When middleware throws, earlier middleware that has already awaited next() should still be able to run its after-logic (e.g. modifying the response). For example, if a header is set after await next(), it should be present in the final response, even if later middleware throws.

Actual Behavior

If a later middleware throws, earlier middleware that already awaited next() doesn’t get a chance to run its after-logic. This makes it impossible to reliably apply global headers, logging or cleanup etc.

export const unstable_middleware: Route.unstable_MiddlewareFunction[] = [
  async (_, next) => {
    const response = await next();
    if (!response.headers.has('Cache-Control')) {
      response.headers.set(
        'Cache-Control',
        'no-store, no-cache, must-revalidate, private'
      );
    }
    return response;
  },
  async () => {
    throw new Error(
      "Throwing here shouldn't prevent earlier middleware from unwinding!"
    );
    // EXPECT: 500 response with Cache-Control header
    // ACTUAL: 500 response without Cache-Control header
  },
];

NOTE: Throwing in the loader or <Component /> works as expected; the Cache-Control header is set.

[AlemTuzlak]

You can wrap the parent with a try/catch and handle it

[sergiodxa]

I would even say that you shouldn't throw non-redirects in middleware functions. If your middleware is setting something in context, set null instead and throw in the loader

[richardscarrott]

You can wrap the parent with a try/catch and handle it

Do you mean try / catch the await next() function in the first middleware? That'd just give me an Error, whereas I want the outbound 500 Response (which contains html or data depending on the request).

I would even say that you shouldn't throw non-redirects in middleware functions. If your middleware is setting something in context, set null instead and throw in the loader

My middleware isn't setting anything on context. It'd be super weird to set a flag on context just to tell my loader to throw?

I think this is a pretty standard middleware expectation tbh. I appreciate RR has some extra complexity due to nested routing, but conceptually I think it still applies (see connect, express, koa, hono etc.).

If it can't guarantee you the opportunity to handle the outbound Response then it's pretty flawed imo.

For example, take a look at this canonical logging use case:

const loggerMiddleware: unstable_MiddlewareFunction = async (
  { request },
  next
) => {
  const response = await next();
  console.log(`${request.method} ${request.url} :: ${response.status} :: ${response.headers.get("Content-Type")}`);
  return response;
};

export const unstable_middleware: unstable_MiddlewareFunction[] = [
  loggerMiddleware,
  async (_, next) => {
    throw redirect('/login');
  },
];

Just because I redirected in a middleware I lose logging — makes no sense?

[richardscarrott]

Looking into this further, I think this could be problematic also:

export const unstable_middleware: unstable_MiddlewareFunction[] = [
  async (_, next) => {
    // This renders the error boundary ✅
    throw Error('Oops');
  },
];

export const unstable_middleware: unstable_MiddlewareFunction[] = [
  async (_, next) => {
    // This doesn't render the error boundary 🚨
    throw new Response(null, { status: 401 });
  },
];

For use cases I've experienced, I'd want middleware to behave the same way as loaders — so throwing an Error or Response would still render the error boundary of the current route.

[richardscarrott]

Another potential issue I've run into is middleware doesn't run when hitting an unmatched route. I've worked around this by defining a $.ts route which throws a 404 in the loader, but this is a little subtle.

// app/routes/$.tsx

import type { Route } from "./+types/route";

export const loader = async ({}: Route.LoaderArgs) => {
  throw new Response(null, { status: 404 });
};

// Opt-out of resource route behaviour (we want the root route to handle errors).
export default () => null;

I think offering a guarantee that middleware is executed before all requests -- be it html or data, matched route or not, would be a very valuable characteristic. Then we can ditch express / hono / whatever middleware, getLoadContext and therefore custom servers altogether.

[brophdawg11]

I just left a semi-related comment on https://discord.com/channels/770287896669978684/1392191816367079507/1399462797196394608 and also updated the docs in dev with some more information on throwing from middlewares.

Middlewares main job is to produce Responses. So you can throw a Response as a short circuit - which tells RR to stop processing and return the response immediately. If you want to continue running the ancestor middlewares, you return the Response. This is just like how normal JS call stacks behave when something is thrown.

But if you throw an error, how is RR supposed to generate a response from that to hand to your ancestor middleware?

If you throw before the next function we never even get a chance to reach the logic that calls handlers and renders HTML via your entry.server file, so there's no possible response to even expose to the ancestor middleware.

Take your provided example (re-worked slightly to add function names we can use for discussion):

async function setHeader(_, next) {
  const response = await next();
  if (!response.headers.has('Cache-Control')) {
    response.headers.set(
      'Cache-Control',
      'no-store, no-cache, must-revalidate, private'
    );
  }
  return response;
}

function throwError() {
  throw new Error("Broken!");
}

export const unstable_middleware: Route.unstable_MiddlewareFunction[] = [
  setHeader, 
  throwError
];

What would you expect to generate the Responseto return from await next() in setHeaders? Your entry.server code effectively lives inside the leaf next function, so by throing you prevent us from ever reaching that.

If you were to throw an Error after the next function, we already have a Response in scope, but we lose it as soon as you throw, so again - there's no Response to expose to the ancestor:

function throwError() {
  let response = await next();
  throw new Error("Broken!");
  // response is lost as son as you do this because we bubble up the call stack
}

[brophdawg11]

Just because I redirected in a middleware I lose logging — makes no sense?

You should be able to return Response's to bubble up. I think that specific example might be surfacing a bug where if you don't call next we call it automatically for you and return it's response. We should not do that if you returned your own Response. I will get that fixed via #14093.

For use cases I've experienced, I'd want middleware to behave the same way as loaders — so throwing an Error or Response would still render the error boundary of the current route.

Middleware runs at an entirely different spot than loaders, so it's incorrect to try to force them into the same paradigms. If you have /a/b/c, the execution order is:

- start A middleware 
- start B middleware 
- start C middleware 
- run A/B/C loaders
- render HTML via entry.server
- end C middleware
- end B middleware
- end A middleware

If you throw from C's middleware - how can we possibly render C's ErrorBoundary if we haven't yet run the loaders for A and B? We have no loaderData to expose to the components for A and B that wrap the C ErrorBoundary.

It's best to think of middleware as "response producers", anything other than that is a fatal error because you're never even reaching the core RR Response generation logic.

If you have real world use cases you're having trouble implementing, please open a discussion and tag me and we can look into the proper middleware patterns for those.

[richardscarrott]

Thanks for the reply @brophdawg11. I’ve been thinking about this more and still believe it’s worth reconsidering — I feel strongly that await next() should never reject. This matches the behaviour in frameworks like Hono, Koa, and Express, where middleware always receives a Response, even if it was generated from an error deeper in the stack — that’s kind of the beauty of middleware, in my opinion.

At a high level, I think there are three distinct scenarios middleware need to support:

1. Middleware hands over to the next middleware
   • Use cases
     • Set something on context
     • Modify the final response (e.g. add headers)
2. Middleware short-circuits by returning its own Response
   • Use cases
     • Basic auth (no response body needed, as the www-authenticate header handles the UI)
     • Redirects (no response body needed)
3. Middleware short-circuits by throwing (Error or Response), and React Router turns it into an appropriate Response (e.g. via root error boundary)
   • Use cases
     • Runtime errors. (500 UI)
     • Auth failures (unlike basic auth, RR handles the UI)
     • 404 (not found UI)

Ultimately, React Router always returns a Response to the client — whether it was produced by RR's HTML / data handler or subsequent middleware. Middleware could therefore be given a guaranteed opportunity to observe or modify that response. Without that, common use cases like logging, setting headers, or cleanup become unreliable, and I think developers will continue relying on external middleware frameworks, with RR acting only as the final handler.