From f1ce75740d0d639999708907fa034cb85b47eb4a Mon Sep 17 00:00:00 2001
From: Bryson Meiling <43580701+Bryson14@users.noreply.github.com>
Date: Sat, 24 Jan 2026 16:22:03 -0800
Subject: [PATCH 1/3] Enhance middleware documentation with error handling
 details

Added explanation for error handling in middleware and provided an example of authentication middleware.
---
 .../start/framework/react/guide/middleware.md | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/start/framework/react/guide/middleware.md b/docs/start/framework/react/guide/middleware.md
index 6578b0d5ca..d31a06fb64 100644
--- a/docs/start/framework/react/guide/middleware.md
+++ b/docs/start/framework/react/guide/middleware.md
@@ -79,6 +79,27 @@ const loggingMiddleware = createMiddleware().server(async ({ next }) => {
 })
 ```
 
+The exception to always returning `next()` to this is throwing errors. By default, throwing an error will cause the router to short-circuit and return the data passed into the `Error` along with a 500 HTTP error code. If you want to return another error code, like with an authentication middlware, you can throw the `json` helper.
+
+```tsx
+import { createMiddleware, json } from "@tanstack/react-start";
+
+const authMiddleware = createMiddleware().server(async ({ next, request }) => {
+  const client = await getMyDb();
+  if (!client) {
+    throw new Error("Oh No!"); // returns a 500 HTTP response to the client
+  }
+  const sessionCookie = request.headers.get("Authorization");
+  const user = client.getUser(sessionCookie);
+  if (!user) {
+    throw json({
+      message: "you shall not pass!"
+    }, {status: 401})
+
+  return await next({ context: { user }}) // pass the user's information to the next middlware or server function
+})
+```
+
 ## Request Middleware
 
 Request middleware is used to customize the behavior of any server request that passes through it, including server routes, SSR and server functions.

From 37121671c1acba1e77045e48ca313d162ab304f6 Mon Sep 17 00:00:00 2001
From: Bryson Meiling <43580701+Bryson14@users.noreply.github.com>
Date: Sat, 24 Jan 2026 16:26:30 -0800
Subject: [PATCH 2/3] Update middleware.md for error handling and async user
 fetch

Clarified error handling behavior in middleware documentation and updated code example to use await for asynchronous user retrieval.
---
 docs/start/framework/react/guide/middleware.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/start/framework/react/guide/middleware.md b/docs/start/framework/react/guide/middleware.md
index d31a06fb64..486de31521 100644
--- a/docs/start/framework/react/guide/middleware.md
+++ b/docs/start/framework/react/guide/middleware.md
@@ -79,7 +79,7 @@ const loggingMiddleware = createMiddleware().server(async ({ next }) => {
 })
 ```
 
-The exception to always returning `next()` to this is throwing errors. By default, throwing an error will cause the router to short-circuit and return the data passed into the `Error` along with a 500 HTTP error code. If you want to return another error code, like with an authentication middlware, you can throw the `json` helper.
+The exception to always returning `next()` is throwing errors. By default, throwing an error will cause the router to short-circuit and return the data passed into the `Error` as a 500 HTTP error-code response. If you want to return another error code, like with an authentication middlware, you can throw the `json` helper.
 
 ```tsx
 import { createMiddleware, json } from "@tanstack/react-start";
@@ -90,7 +90,7 @@ const authMiddleware = createMiddleware().server(async ({ next, request }) => {
     throw new Error("Oh No!"); // returns a 500 HTTP response to the client
   }
   const sessionCookie = request.headers.get("Authorization");
-  const user = client.getUser(sessionCookie);
+  const user = await client.getUser(sessionCookie);
   if (!user) {
     throw json({
       message: "you shall not pass!"

From 344151c15a92123de1dbcabedffb2f3c670d2b86 Mon Sep 17 00:00:00 2001
From: Bryson Meiling <43580701+Bryson14@users.noreply.github.com>
Date: Sat, 24 Jan 2026 20:24:54 -0800
Subject: [PATCH 3/3] Fix formatting issues in middleware documentation

---
 docs/start/framework/react/guide/middleware.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/start/framework/react/guide/middleware.md b/docs/start/framework/react/guide/middleware.md
index 486de31521..276d7ef064 100644
--- a/docs/start/framework/react/guide/middleware.md
+++ b/docs/start/framework/react/guide/middleware.md
@@ -79,7 +79,7 @@ const loggingMiddleware = createMiddleware().server(async ({ next }) => {
 })
 ```
 
-The exception to always returning `next()` is throwing errors. By default, throwing an error will cause the router to short-circuit and return the data passed into the `Error` as a 500 HTTP error-code response. If you want to return another error code, like with an authentication middlware, you can throw the `json` helper.
+The exception to always returning `next()` is throwing errors. By default, throwing an error will cause the router to short-circuit and return the data passed into the `Error` as a 500 HTTP error-code response. If you want to return another error code, like with an authentication middleware, you can throw the `json` helper.
 
 ```tsx
 import { createMiddleware, json } from "@tanstack/react-start";
@@ -95,6 +95,7 @@ const authMiddleware = createMiddleware().server(async ({ next, request }) => {
     throw json({
       message: "you shall not pass!"
     }, {status: 401})
+  }
 
   return await next({ context: { user }}) // pass the user's information to the next middlware or server function
 })