Catch block in middleware function never catches anything

[rossipedia]

Reproduction

https://github.com/rossipedia/rr-middleware-catch
https://stackblitz.com/~/rossipedia/rr-middleware-catch

1. Start this app:

   npm install
   npm run dev

2. Make a request to http://localhost:5173

Per the docs, you should see a message:

Route error: error

in the terminal where you ran npm run dev. However, that message is not present, leading to the conclusion that the catch block in the middleware function is never executed.

System Info

System:
    OS: macOS 15.5
    CPU: (16) arm64 Apple M4 Max
    Memory: 9.08 GB / 64.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 24.4.1 - ~/.local/state/fnm_multishells/35301_1752789017672/bin/node
    Yarn: 1.22.22 - ~/.local/state/fnm_multishells/35301_1752789017672/bin/yarn
    npm: 11.4.2 - ~/src/rr/rr-middleware-catch/node_modules/.bin/npm
    pnpm: 10.12.1 - ~/.local/state/fnm_multishells/35301_1752789017672/bin/pnpm
    bun: 1.2.18 - /opt/homebrew/bin/bun
  Browsers:
    Chrome: 138.0.7204.101
    Safari: 18.5
  npmPackages:
    @react-router/dev: ^7.7.0 => 7.7.0 
    @react-router/fs-routes: ^7.7.0 => 7.7.0 
    @react-router/node: ^7.7.0 => 7.7.0 
    @react-router/serve: ^7.7.0 => 7.7.0 
    react-router: ^7.7.0 => 7.7.0 
    vite: ^6.3.5 => 6.3.5

Used Package Manager

npm

Expected Behavior

I should see the output from the middleware catch block

Actual Behavior

I do not see the output from the middleware catch block

[brophdawg11]

Potentially related to #13936

[brophdawg11]

I think this is working as intended and is just a docs mistake - my fault because I used an LLM to help write those docs and didn't catch that example 🤦

This also probably means the docs don't cover this well enough. I'm going to brain dump a bit here but will get this polished up into the docs too.

Middleware is designed as:

• Run matched route middlewares top-down
• Generate a Response from the leaf next()
• Bubble that Response back up the middlewares

next really shouldn't throw in "normal" cases. If a loader/action throws, we handle that and render the appropriate ErrorBoundary into a Response which is returned up the next chain. next would only throw if a fatal error occurred while we were trying to generate the Response and we couldn't.

The use case for throwing from a middleware is to say "return this response right now and don't run anything else" - it's basically a short circuit and usually used with a redirect:

1. redirecting before calling next (auth)

function authMiddleware({ context, request }) {
  if (!isLoggedIn(context, request)) throw redirect('/login')
}

2. redirecting after next (CMS redirect lookups on 404s)

async function cmsRedirectMiddleware({ context, request }, next) {
  let response = await next();
  if (response.status === 404) {
    let path = await getCmsRedirectPath(request.url);
    if (path) throw redirect(path);
  }
  return response.
}

If next threw when a loader/action threw, even when we generated an ErrorBoundary response, we'd skip all the ancestor middlewares and would miss out on potentially important headers being set higher up (the most common use case is automatically committing the session in a root middleware).

That example in the docs could probably just be removed since middleware really isn't the right place for error handling. Reporting errors should happen in handleError and generating HTML for the Response should be done in the ErrorBoundary.

If we did want to do something "error" related in middleware it might be more along the lines of morgan-esque logging:

async function errorMiddleware({ context }, next) {
  let response = await next();
  if (response.status >= 500) {
    console.log(request.status, request.url);
  }
  return response;
};