docs: add new troubleshooting guides for Query and middlewares (#12214)

www/apps/resources/app/troubleshooting/_sections/api-routes/middleware-file-name.mdx

@@ -0,0 +1,5 @@
+A common mistake when creating middlewares is naming the file `middleware.ts` rather than `middlewares.ts`.
+
+If your middleware isn't registered correctly, make sure you've created the middleware file at `src/api/middlewares.ts`.
+
+Learn more in the [Middleware](!docs!/learn/fundamentals/api-routes/middlewares) documentation.

www/apps/resources/app/troubleshooting/_sections/query/expression-type-error.mdx

@@ -0,0 +1,41 @@
+import { CodeTab, CodeTabs } from "docs-ui"
+
+If you get the following error while using `query.graph` or `useQueryGraphStep`:
+
+```bash
+Expression produces a union type that is too complex to represent. ts(2590)
+```
+
+## Why this Error Occurred
+
+This type error may occur when you use Query, but it's only a type error that doesn't affect the functionality of your code. It occurs because the models you're retrieving may be too complicated for the TypeScript compiler to infer the types correctly.
+
+---
+
+## How to Fix it
+
+You can ignore this error by using the `// @ts-ignore` directive before the line of code that produces the error. For example:
+
+<CodeTabs group="query">
+  <CodeTab label="query.graph" value="query.graph">
+
+```ts
+// @ts-ignore
+const { data } = await query.graph({
+  // ...
+})
+```
+
+  </CodeTab>
+  <CodeTab label="useQueryGraphStep" value="useQueryGraphStep">
+
+```ts
+// @ts-ignore
+const { data } = useQueryGraphStep({
+  // ...
+})
+```
+
+  </CodeTab>
+
+</CodeTabs>

www/apps/resources/app/troubleshooting/api-routes/additional-data-error/page.mdx

@@ -1,4 +1,4 @@
-import AdditionalDataError from "../_sections/api-routes/additional-data.mdx"
+import AdditionalDataError from "../../_sections/api-routes/additional-data.mdx"
 
 export const metadata = {
   title: `Unrecognized fields \`additiona_data\` Error`,

www/apps/resources/app/troubleshooting/api-routes/middleware-registration/page.mdx

@@ -0,0 +1,13 @@
+import MiddlewareFileName from "../../_sections/api-routes/middleware-file-name.mdx"
+
+export const metadata = {
+  title: `Middleware Registration Troubleshooting`,
+}
+
+# {metadata.title}
+
+This troubleshooting guide will help you debug why your middleware is not being registered correctly.
+
+## Incorrect Middleware File Name
+
+<MiddlewareFileName />

www/apps/resources/app/troubleshooting/query/expression-type-error/page.mdx

@@ -0,0 +1,9 @@
+import ExpressionTypeError from "../../_sections/query/expression-type-error.mdx"
+
+export const metadata = {
+  title: `Error: Expression produces a union type that is too complex to represent`,
+}
+
+# {metadata.title}
+
+<ExpressionTypeError />

www/apps/resources/generated/edit-dates.mjs

@@ -6059,7 +6059,6 @@ export const generatedEditDates = {
   "app/storefront-development/cart/totals/page.mdx": "2025-03-27T14:47:14.252Z",
   "app/storefront-development/checkout/order-confirmation/page.mdx": "2025-03-27T14:29:45.669Z",
   "app/how-to-tutorials/tutorials/product-reviews/page.mdx": "2025-04-17T08:48:08.716Z",
-  "app/troubleshooting/api-routes/page.mdx": "2025-03-21T07:17:56.248Z",
   "app/troubleshooting/data-models/default-fields/page.mdx": "2025-03-21T06:59:06.775Z",
   "app/troubleshooting/medusa-admin/blocked-request/page.mdx": "2025-03-21T06:53:34.854Z",
   "app/troubleshooting/nextjs-starter-rewrites/page.mdx": "2025-03-21T07:09:08.901Z",
@@ -6146,5 +6145,8 @@ export const generatedEditDates = {
   "references/types/interfaces/types.IFulfillmentProvider/page.mdx": "2025-04-11T09:04:46.137Z",
   "references/user/types/user.Message/page.mdx": "2025-04-11T09:04:52.767Z",
   "app/infrastructure-modules/workflow-engine/how-to-use/page.mdx": "2025-03-27T14:53:13.311Z",
-  "references/core_flows/Notification/Steps_Notification/functions/core_flows.Notification.Steps_Notification.notifyOnFailureStep/page.mdx": "2025-04-17T08:42:33.837Z"
+  "references/core_flows/Notification/Steps_Notification/functions/core_flows.Notification.Steps_Notification.notifyOnFailureStep/page.mdx": "2025-04-17T08:42:33.837Z",
+  "app/troubleshooting/api-routes/additional-data-error/page.mdx": "2025-03-27T17:39:10.858Z",
+  "app/troubleshooting/api-routes/middleware-registration/page.mdx": "2025-04-17T10:35:42.095Z",
+  "app/troubleshooting/query/expression-type-error/page.mdx": "2025-04-17T10:30:39.317Z"
 }

www/apps/resources/generated/files-map.mjs

@@ -1264,8 +1264,12 @@ export const filesMap = [
     "pathname": "/tools"
   },
   {
-    "filePath": "/www/apps/resources/app/troubleshooting/api-routes/page.mdx",
+    "filePath": "/www/apps/resources/app/troubleshooting/api-routes/additional-data-error/page.mdx",
-    "pathname": "/troubleshooting/api-routes"
+    "pathname": "/troubleshooting/api-routes/additional-data-error"
+  },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/api-routes/middleware-registration/page.mdx",
+    "pathname": "/troubleshooting/api-routes/middleware-registration"
   },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/cors-errors/page.mdx",
@@ -1319,6 +1323,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/page.mdx",
     "pathname": "/troubleshooting"
   },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/query/expression-type-error/page.mdx",
+    "pathname": "/troubleshooting/query/expression-type-error"
+  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/query/filter-linked/page.mdx",
     "pathname": "/troubleshooting/query/filter-linked"

www/apps/resources/generated/generated-troubleshooting-sidebar.mjs

@@ -69,15 +69,31 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
       "type": "category",
       "title": "Framework",
       "initialOpen": true,
+      "children": [
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "sub-category",
+          "title": "API Routes",
           "children": [
             {
               "loaded": true,
               "isPathHref": true,
               "type": "link",
-          "path": "/troubleshooting/eaddrinuse",
+              "title": "Unrecognized Additional Data",
-          "title": "EADDRINUSE Error",
+              "path": "/troubleshooting/api-routes/additional-data-error",
               "children": []
             },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "title": "Middleware Registration",
+              "path": "/troubleshooting/api-routes/middleware-registration",
+              "children": []
+            }
+          ]
+        },
         {
           "loaded": true,
           "isPathHref": true,
@@ -86,6 +102,14 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
           "title": "Database Errors",
           "children": []
         },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "link",
+          "path": "/troubleshooting/eaddrinuse",
+          "title": "EADDRINUSE Error",
+          "children": []
+        },
         {
           "loaded": true,
           "isPathHref": true,
@@ -100,6 +124,14 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
           "type": "sub-category",
           "title": "Query",
           "children": [
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/troubleshooting/query/expression-type-error",
+              "title": "Expression Type Error",
+              "children": []
+            },
             {
               "loaded": true,
               "isPathHref": true,
@@ -107,9 +139,25 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
               "path": "/troubleshooting/query/filter-linked",
               "title": "Not Exising Property",
               "children": []
+            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/troubleshooting/query/service-list",
+              "title": "service.list Error",
+              "children": []
             }
           ]
         },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "link",
+          "path": "/troubleshooting/test-errors",
+          "title": "Test Errors",
+          "children": []
+        },
         {
           "loaded": true,
           "isPathHref": true,
@@ -133,14 +181,6 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
               "children": []
             }
           ]
-        },
-        {
-          "loaded": true,
-          "isPathHref": true,
-          "type": "link",
-          "path": "/troubleshooting/test-errors",
-          "title": "Test Errors",
-          "children": []
         }
       ]
     },

www/apps/resources/sidebars/troubleshooting.mjs

@@ -46,17 +46,33 @@ export const troubleshootingSidebar = [
     type: "category",
     title: "Framework",
     initialOpen: true,
+    children: [
+      {
+        type: "sub-category",
+        title: "API Routes",
         children: [
           {
             type: "link",
-        path: "/troubleshooting/eaddrinuse",
+            title: "Unrecognized Additional Data",
-        title: "EADDRINUSE Error",
+            path: "/troubleshooting/api-routes/additional-data-error",
+          },
+          {
+            type: "link",
+            title: "Middleware Registration",
+            path: "/troubleshooting/api-routes/middleware-registration",
+          },
+        ],
       },
       {
         type: "link",
         path: "/troubleshooting/database-errors",
         title: "Database Errors",
       },
+      {
+        type: "link",
+        path: "/troubleshooting/eaddrinuse",
+        title: "EADDRINUSE Error",
+      },
       {
         type: "link",
         path: "/troubleshooting/dist-imports",
@@ -66,13 +82,28 @@ export const troubleshootingSidebar = [
         type: "sub-category",
         title: "Query",
         children: [
+          {
+            type: "link",
+            path: "/troubleshooting/query/expression-type-error",
+            title: "Expression Type Error",
+          },
           {
             type: "link",
             path: "/troubleshooting/query/filter-linked",
             title: "Not Exising Property",
           },
+          {
+            type: "link",
+            path: "/troubleshooting/query/service-list",
+            title: "service.list Error",
+          },
         ],
       },
+      {
+        type: "link",
+        path: "/troubleshooting/test-errors",
+        title: "Test Errors",
+      },
       {
         type: "sub-category",
         title: "Workflows",
@@ -89,11 +120,6 @@ export const troubleshootingSidebar = [
           },
         ],
       },
-      {
-        type: "link",
-        path: "/troubleshooting/test-errors",
-        title: "Test Errors",
-      },
     ],
   },
   {