docs: triage issues + revamp troubleshooting guides (#14216)

* docs: triage issues + revamp troubleshooting guides

* small change

Author: shahednasser

www/apps/book/app/learn/installation/page.mdx

@@ -28,15 +28,15 @@ While this is the recommended way to create a Medusa application, you can altern
 
 <Prerequisites items={[
   {
-    text: "Node.js v20+ (LTS versions)",
+    text: "Node.js v20+ (LTS versions only)",
     link: "https://nodejs.org/en/download"
   },
   {
     text: "Git CLI tool",
     link: "https://git-scm.com/downloads"
   },
   {
-    text: "PostgreSQL",
+    text: "PostgreSQL installed and running",
     link: "https://www.postgresql.org/download/"
   }
 ]} />

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

@@ -96,7 +96,7 @@ export const generatedEditDates = {
   "app/learn/build/page.mdx": "2025-10-27T09:30:26.957Z",
   "app/learn/deployment/general/page.mdx": "2025-10-21T07:39:08.998Z",
   "app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2025-08-01T14:59:59.501Z",
-  "app/learn/installation/page.mdx": "2025-11-26T12:14:47.372Z",
+  "app/learn/installation/page.mdx": "2025-12-04T14:30:00.510Z",
   "app/learn/fundamentals/data-models/check-constraints/page.mdx": "2025-07-25T13:50:21.065Z",
   "app/learn/fundamentals/module-links/link/page.mdx": "2025-11-28T13:42:03.037Z",
   "app/learn/fundamentals/workflows/store-executions/page.mdx": "2025-04-17T08:29:10.166Z",

www/apps/book/public/llms-full.txt

@@ -25386,9 +25386,9 @@ While this is the recommended way to create a Medusa application, you can altern
 
 ### Prerequisites
 
-- [Node.js v20+ (LTS versions)](https://nodejs.org/en/download)
+- [Node.js v20+ (LTS versions only)](https://nodejs.org/en/download)
 - [Git CLI tool](https://git-scm.com/downloads)
-- [PostgreSQL](https://www.postgresql.org/download/)
+- [PostgreSQL installed and running](https://www.postgresql.org/download/)
 
 To create a Medusa application, use the `create-medusa-app` command:
 
@@ -46123,7 +46123,7 @@ const step1 = createStep(
   "step-1",
   async ({}, { container }) => {
     const eventModuleService = container.resolve(
-      Modules.EVENT
+      Modules.EVENT_BUS
     )
 
     await eventModuleService.emit({
@@ -46162,7 +46162,7 @@ Medusa provides the following Event Modules. You can use one of them, or [Create
 
 The Redis Event Module uses Redis to implement Medusa's pub/sub events system.
 
-It's powered by BullMQ and `io-redis`. BullMQ is responsible for the message queue and worker, and `io-redis` is the underlying Redis client that BullMQ connects to for events storage.
+It's powered by [BullMQ](https://bullmq.io/) and `io-redis`. BullMQ is responsible for the message queue and worker, and `io-redis` is the underlying Redis client that BullMQ connects to for events storage.
 
 In production, it's recommended to use this module.
 
@@ -46190,6 +46190,19 @@ module.exports = defineConfig({
       resolve: "@medusajs/medusa/event-bus-redis",
       options: { 
         redisUrl: process.env.EVENTS_REDIS_URL,
+        // suggested additional options for production use
+        jobOptions: {
+          removeOnComplete: {
+            // keep jobs for 1 hour or up to 1000 jobs
+            age: 3600,
+            count: 1000,
+          },
+          removeOnFail: {
+            // keep jobs for 1 hour or up to 1000 jobs
+            age: 3600,
+            count: 1000,
+          }
+        }
       },
     },
   ],

www/apps/resources/app/infrastructure-modules/event/page.mdx

@@ -45,7 +45,7 @@ const step1 = createStep(
   "step-1",
   async ({}, { container }) => {
     const eventModuleService = container.resolve(
-      Modules.EVENT
+      Modules.EVENT_BUS
     )
 
     await eventModuleService.emit({

www/apps/resources/app/infrastructure-modules/event/redis/page.mdx

@@ -8,7 +8,7 @@ export const metadata = {
 
 The Redis Event Module uses Redis to implement Medusa's pub/sub events system.
 
-It's powered by BullMQ and `io-redis`. BullMQ is responsible for the message queue and worker, and `io-redis` is the underlying Redis client that BullMQ connects to for events storage.
+It's powered by [BullMQ](https://bullmq.io/) and `io-redis`. BullMQ is responsible for the message queue and worker, and `io-redis` is the underlying Redis client that BullMQ connects to for events storage.
 
 In production, it's recommended to use this module.
 
@@ -47,6 +47,19 @@ module.exports = defineConfig({
       resolve: "@medusajs/medusa/event-bus-redis",
       options: { 
         redisUrl: process.env.EVENTS_REDIS_URL,
+        // suggested additional options for production use
+        jobOptions: {
+          removeOnComplete: {
+            // keep jobs for 1 hour or up to 1000 jobs
+            age: 3600,
+            count: 1000,
+          },
+          removeOnFail: {
+            // keep jobs for 1 hour or up to 1000 jobs
+            age: 3600,
+            count: 1000,
+          }
+        }
       },
     },
   ],

www/apps/resources/app/storefront-development/customers/register/page.mdx

@@ -28,12 +28,12 @@ To register a customer, you implement the following steps:
 
 1. Show the customer a form to enter their details.
 2. Send a `POST` request to the `/auth/customer/emailpass/register` [Get Registration Token](!api!/store#auth_postactor_typeauth_provider_register) API route to obtain a registration JWT token.
-3. Send a request to the [Create Customer API route](!api!/store#customers_postcustomers) passing the registration JWT token in the header.
+3. Send a request to the [Register Customer API route](!api!/store#customers_postcustomers) passing the registration JWT token in the header.
 
 However, a customer may enter an email that's already used either by an admin user, another customer, or a [custom actor type](../../../commerce-modules/auth/auth-identity-and-actor-types/page.mdx). To handle this scenario:
 
 - Try to obtain a login token by sending a `POST` request to the `/auth/customer/emailpass` [Authenticate Customer](!api!/store#auth_postactor_typeauth_provider) API route. The customer is only allowed to register if their email and password match the existing identity. This allows admin users to log in or register as customers.
-- If you obtained the login token successfully, create the customer using the login JWT token instead of the registration token. This will not remove the existing identity. So, for example, an admin user can also become a customer.
+- If you obtained the login token successfully, register the customer using the login JWT token instead of the registration token. This will not remove the existing identity. So, for example, an admin user can also become a customer.
 
 When you're using the JS SDK, this flow is simplified with quick registration and login methods. The rest of this guide uses the JS SDK to demonstrate the registration flow. However, if you're not using the JS SDK, you can still implement the same flow using the API routes.
 
@@ -186,7 +186,7 @@ export const fetchHighlights = [
   ["11", "catch", "Maybe another identity exists with the same email."],
   ["21", "login", "Try to obtain a login JWT token."],
   ["24", "catch", "The existing account belongs to another customer, so authentication failed."],
-  ["40", "create", "Send a request to create the customer."],
+  ["40", "create", "Send a request to register the customer."],
   ["47", "TODO", "Redirect the customer to the log in page."],
   ["48", "catch", "Handle registration failure"],
 ]
@@ -211,7 +211,7 @@ export const fetchHighlights = [
       }
       // another identity (for example, admin user)
       // exists with the same email. So, use the auth
-      // flow to login and create a customer.
+      // flow to login and register a customer.
       const loginResponse = (await sdk.auth.login("customer", "emailpass", {
         email,
         password,
@@ -229,7 +229,7 @@ export const fetchHighlights = [
       }
     }
 
-    // create customer
+    // register customer
     try {
       const { customer } = await sdk.store.customer.create({
         first_name: firstName,
@@ -256,7 +256,7 @@ In the above example, you create a `handleRegistration` function that:
     - If the error is an existing identity error, try retrieving the login JWT token from `/auth/customer/emailpass` API route using the `auth.login` method. This will fail if the existing identity has a different password, which doesn't allow the customer from registering.
     - For other errors, show an alert and exit execution.
     - The JS SDK automatically stores an re-uses the authentication headers or session in the `auth.register` and `auth.login` methods. So, if you're not using the JS SDK, make sure to pass the received authentication tokens as explained in the [API reference](!api!/store#1-bearer-authorization-with-jwt-tokens)
-- Send a request to the [Create Customer API route](!api!/store#customers_postcustomers) to create the customer in Medusa.
+- Send a request to the [Register Customer API route](!api!/store#customers_postcustomers) to register the customer in Medusa.
     - If an error occurs, show an alert and exit execution.
     - As mentioned, the JS SDK automatically sends the authentication headers or session in all requests after registration or logging in. If you're not using the JS SDK, make sure to pass the received authentication tokens as explained in the [API reference](!api!/store#1-bearer-authorization-with-jwt-tokens).
 - Once the customer is registered successfully, you can either redirect the customer to the login page or log them in automatically, as explained in the [Login](../login/page.mdx) guide.

www/apps/resources/app/troubleshooting/_sections/database-errors/sasl.mdx

@@ -1,18 +1,26 @@
-You may get the following error while running `medusa new`:
+When installing or running Medusa, you may get errors while Medusa tries to connect to your PostgreSQL database.
+
+For example, you may get one of the following errors:
 
 ```bash
+Error: connect ECONNREFUSED ::1:5432
 Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string
 ```
 
-If the error occurs while running `medusa new` and you've selected to enter your database credentials, either:
+### Error During Installation
 
-1. Make sure your database credentials are correct;
-2. Or choose the Skip option to skip entering your database credentials.
+If the connectivity error occurs while running `create-medusa-app`, it means you passed incorrect database credentials when prompted during the installation. Make sure that:
 
-If the error occurs while running integration tests, make sure the following variable is set in your system's environment variable:
+1. PostgreSQL is installed and running on your machine;
+2. Your PostgreSQL server is configured at `localhost:5432` (the default host and port); If not, you can pass the `--db-url <url>` flag to the `create-medusa-app` command to specify a custom database URL;
+3. You're passing correct username and password for your PostgreSQL database;
+4. You're using a user that has privileges to create new databases;
+5. You're passing correct database name for your PostgreSQL user. It should have the same name as your PostgreSQL user by default.
 
-```bash
-DB_HOST=<YOUR_DB_HOST>
-DB_USERNAME=<YOUR_DB_USERNAME>
-DB_PASSWORD=<YOUR_PASSWORD>
-```
+### Error During Development
+
+If the error occurs while running integration tests, make sure that:
+
+1. The `DATABASE_URL` environment variable is set correctly in your `.env` file;
+2. The [projectConfig.databaseUrl](!docs!/learn/configurations/medusa-config#databaseurl) field in your `medusa-config.js` file is set to the `DATABASE_URL` environment variable;
+3. The database URL is using correct username and password, and points to a running PostgreSQL database instance.

www/apps/resources/app/troubleshooting/create-medusa-app-errors/page.mdx

@@ -5,13 +5,23 @@ import InvalidTokenError from "../_sections/create-medusa-app-errors/no-browser-
 import DockerSection from "../_sections/database-errors/docker.mdx"
 import DbUrlError from "../_sections/create-medusa-app-errors/db-url-error.mdx"
 import ForwardingError from "../_sections/create-medusa-app-errors/forwarding.mdx"
+import SaslSection from '../_sections/database-errors/sasl.mdx'
+import ModuleXErrorSection from '../_sections/common-installation-errors/module-x-error.mdx'
 
 export const metadata = {
   title: `Common create-medusa-app Errors`,
 }
 
 # {metadata.title}
 
+This troubleshooting guide covers common errors you may encounter when using the `create-medusa-app` command to set up a new Medusa application and how to resolve them.
+
+## General Errors Connecting to Database
+
+<SaslSection />
+
+---
+
 ## TypeError: cmd is not a function
 
 <TypeError />
@@ -48,6 +58,12 @@ export const metadata = {
 
 ---
 
+## Resolve "Cannot find module X" Errors
+
+<ModuleXErrorSection />
+
+---
+
 ## Other Errors
 
 <OtherErrors />

www/apps/resources/app/troubleshooting/database-errors/page.mdx

@@ -1,6 +1,5 @@
 import SaslSection from '../_sections/database-errors/sasl.mdx'
 import ConnectionErrorSection from '../_sections/database-errors/connection-error.mdx'
-import PrivilegesSection from '../_sections/database-errors/privileges.mdx'
 import DockerSection from "../_sections/database-errors/docker.mdx"
 
 export const metadata = {
@@ -9,24 +8,14 @@ export const metadata = {
 
 # {metadata.title}
 
-## Can't Connect to PostgreSQL Docker Container
-
-<DockerSection />
+This troubleshooting guide covers common database errors you may encounter when working with Medusa and how to resolve them.
 
----
-
-## Error: SASL: SCRAM-SERVER-FIRST-MESSAGE: Client password must be a string
+## General Errors Connecting to Database
 
 <SaslSection />
 
 ---
 
-## Error: connect ECONNREFUSED ::1:5432
-
-<ConnectionErrorSection />
-
----
-
-## Database User Privileges
+## Can't Connect to PostgreSQL Docker Container
 
-<PrivilegesSection />
+<DockerSection />

www/apps/resources/app/troubleshooting/errors-after-upgrading/page.mdx

@@ -1,15 +1,19 @@
 export const metadata = {
-  title: `Errors After Upgrading`,
+  title: `Errors After Upgrading Medusa`,
 }
 
 # {metadata.title}
 
-If you run into errors after updating Medusa and its dependencies, it's highly recommended to check the Upgrade Guides if there is a specific guide for your version. These guides include steps required to perform after upgrading Medusa.
+If you run into errors after updating your Medusa application, it's highly recommended to check the [GitHub Release Notes](https://github.com/medusajs/medusa/releases) for any upgrade guides related to the version you upgraded to. These release notes may include details on breaking changes and how to resolve them before upgrading.
 
-If there's no upgrade guide for your version, make sure that you ran the `db:migrate` command in the root directory of your Medusa application:
+Also, after updating your Medusa application, make sure that you ran the `db:migrate` command in the root directory of your Medusa application:
 
 ```bash
 npx medusa db:migrate
 ```
 
 This ensures your application has the latest database structure required. Then, try running your Medusa application again and check whether the same error occurs.
+
+## Additional Resources
+
+- [Updating Medusa](!docs!/learn/update)