docs: add troubleshooting for subscribers + scheduled jobs not working (#13762)

www/apps/book/app/learn/fundamentals/events-and-subscribers/page.mdx

@@ -94,6 +94,10 @@ Sending confirmation email...
 
 The first message indicates that the `order.placed` event was emitted, and the second one is the message logged from the subscriber.
 
+### Troubleshooting Subscribers
+
+If your subscriber is not working as expected, refer to the [Subscriber Troubleshooting Guide](!resources!/troubleshooting/subscribers/not-working).
+
 ---
 
 ## Event Module

www/apps/book/app/learn/fundamentals/scheduled-jobs/page.mdx

@@ -79,6 +79,10 @@ After a minute, the following message will be logged to the terminal:
 info:    Greeting!
 ```
 
+### Troubleshooting Scheduled Jobs
+
+If your scheduled job is not running at the expected times, refer to the [Scheduled Job Troubleshooting Guide](!resources!/troubleshooting/scheduled-job-not-running).
+
 ---
 
 ## Example: Sync Products Once a Day

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

@@ -1,5 +1,5 @@
 export const generatedEditDates = {
-  "app/learn/fundamentals/scheduled-jobs/page.mdx": "2025-07-25T15:56:17.926Z",
+  "app/learn/fundamentals/scheduled-jobs/page.mdx": "2025-10-16T09:35:54.393Z",
   "app/learn/fundamentals/workflows/page.mdx": "2024-12-09T14:45:17.837Z",
   "app/learn/deployment/page.mdx": "2025-09-29T10:25:29.915Z",
   "app/learn/page.mdx": "2025-06-27T11:39:15.941Z",
@@ -15,7 +15,7 @@ export const generatedEditDates = {
   "app/learn/fundamentals/medusa-container/page.mdx": "2025-07-25T13:18:36.859Z",
   "app/learn/fundamentals/api-routes/page.mdx": "2025-07-25T15:19:33.365Z",
   "app/learn/fundamentals/modules/modules-directory-structure/page.mdx": "2025-07-25T15:40:20.362Z",
-  "app/learn/fundamentals/events-and-subscribers/page.mdx": "2025-05-16T13:40:16.111Z",
+  "app/learn/fundamentals/events-and-subscribers/page.mdx": "2025-10-16T09:36:04.864Z",
   "app/learn/fundamentals/modules/container/page.mdx": "2025-07-31T14:24:04.087Z",
   "app/learn/fundamentals/workflows/execute-another-workflow/page.mdx": "2025-08-01T07:28:51.036Z",
   "app/learn/fundamentals/modules/loaders/page.mdx": "2025-06-16T13:34:16.462Z",

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

@@ -12038,6 +12038,10 @@ Sending confirmation email...
 
 The first message indicates that the `order.placed` event was emitted, and the second one is the message logged from the subscriber.
 
+### Troubleshooting Subscribers
+
+If your subscriber is not working as expected, refer to the [Subscriber Troubleshooting Guide](https://docs.medusajs.com/resources/troubleshooting/subscribers/not-working/index.html.md).
+
 ***
 
 ## Event Module
@@ -15406,7 +15410,7 @@ In this case, the relation would always be one-to-many, even if only one post is
 
 Whether you're using a one-to-one or one-to-many relation for an inverse read-only module link, the relation name is always the alias of the second data model. It's not changed to its plural form for one-to-many relations.
 
-For example, looking again at the the forced one-to-many relation example:
+For example, looking again at the forced one-to-many relation example:
 
 ```ts
 import BlogModule from "../modules/blog"
@@ -18509,6 +18513,10 @@ After a minute, the following message will be logged to the terminal:
 info:    Greeting!
 ```
 
+### Troubleshooting Scheduled Jobs
+
+If your scheduled job is not running at the expected times, refer to the [Scheduled Job Troubleshooting Guide](https://docs.medusajs.com/resources/troubleshooting/scheduled-job-not-running/index.html.md).
+
 ***
 
 ## Example: Sync Products Once a Day

www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running-worker-mode.mdx

@@ -0,0 +1,55 @@
+If your scheduled job isn't running at all, it may be because your Medusa application is not running in [worker mode](!docs!/learn/production/worker-mode).
+
+<Note>
+
+If you're a Cloud user and this issue is happening on your deployed Medusa application, contact support for assistance.
+
+</Note>
+
+### Why this Happens
+
+By default, the Medusa application runs both the server, which handles all incoming requests, and the worker, which processes background tasks, in a single process.
+
+In production, you should deploy two separate instances of your Medusa application: one for the server and one for the worker.
+
+However, if you deploy only a server instance, or if you accidentally set the worker mode to `server`, the scheduled jobs won't run because there is no worker process to handle them.
+
+### How to Fix it
+
+#### Deploy a Worker Instance
+
+If you haven't deployed a worker instance of your Medusa application, do so by following the steps in the [Worker Mode of Medusa Instance](!docs!/learn/production/worker-mode) guide.
+
+For example, you should have the following configuration in your `medusa-config.ts` file:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  projectConfig: {
+    workerMode: process.env.WORKER_MODE || "shared",
+    // ...
+  },
+  // ...
+})
+```
+
+In your deployed server Medusa instance, set `WORKER_MODE` to `server`, and in your deployed worker Medusa instance, set `WORKER_MODE` to `worker`.
+
+#### Set the Correct Worker Mode
+
+If this issue is happening locally, ensure that you set the correct worker mode in your `medusa-config.ts` file.
+
+When running the server locally, either don't set the `workerMode` configuration or set it to `shared` in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  projectConfig: {
+    workerMode: "shared", // or don't set it at all
+    // ...
+  },
+  // ...
+})
+```
+
+#### Additional Resources
+
+- [Worker Mode](!docs!/learn/production/worker-mode)

www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running.mdx

@@ -1,14 +1,12 @@
 If you have a scheduled job that is configured with a cron expression, it may not run at the expected times sometimes.
 
-## Why this Happens
+### Why this Happens
 
 When a scheduled job is configured with a cron expression, it will only run when the specified time is reached.
 
 So, if the events system is busy and the specified time is missed, the job will not run until the next scheduled time.
 
----
+### How to Fix it
-
-## How to Fix it
 
 If you prioritize running your scheduled jobs consistently over precise timing, consider using a scheduled job interval instead.
 
@@ -33,8 +31,6 @@ export const config = {
 }
 ```
 
----
+### Additional Resources
-
-## Additional Resources
 
 - [Set Interval for Scheduled Jobs](!docs!/learn/fundamentals/scheduled-jobs/interval)

www/apps/resources/app/troubleshooting/_sections/subscribers/not_running_workermode.mdx

@@ -0,0 +1,55 @@
+If you emit an event, but subscribers listening to that event don't run, it may be because your Medusa application is not running in [worker mode](!docs!/learn/production/worker-mode).
+
+<Note>
+
+If you're a Cloud user and this issue is happening on your deployed Medusa application, contact support for assistance.
+
+</Note>
+
+### Why this Happens
+
+By default, the Medusa application runs both the server, which handles all incoming requests, and the worker, which processes background tasks, in a single process.
+
+In production, you should deploy two separate instances of your Medusa application: one for the server and one for the worker.
+
+However, if you deploy only a server instance, or if you accidentally set the worker mode to `server`, the subscribers won't run because there is no worker process to handle them.
+
+### How to Fix it
+
+#### Deploy a Worker Instance
+
+If you haven't deployed a worker instance of your Medusa application, do so by following the steps in the [Worker Mode of Medusa Instance](!docs!/learn/production/worker-mode) guide.
+
+For example, you should have the following configuration in your `medusa-config.ts` file:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  projectConfig: {
+    workerMode: process.env.WORKER_MODE || "shared",
+    // ...
+  },
+  // ...
+})
+```
+
+In your deployed server Medusa instance, set `WORKER_MODE` to `server`, and in your deployed worker Medusa instance, set `WORKER_MODE` to `worker`.
+
+#### Set the Correct Worker Mode
+
+If this issue is happening locally, ensure that you set the correct worker mode in your `medusa-config.ts` file.
+
+When running the server locally, either don't set the `workerMode` configuration or set it to `shared` in `medusa-config.ts`:
+
+```ts title="medusa-config.ts"
+module.exports = defineConfig({
+  projectConfig: {
+    workerMode: "shared", // or don't set it at all
+    // ...
+  },
+  // ...
+})
+```
+
+#### Additional Resources
+
+- [Worker Mode](!docs!/learn/production/worker-mode)

www/apps/resources/app/troubleshooting/scheduled-job-not-running/page.mdx

@@ -1,4 +1,5 @@
 import NotRunning from "../_sections/scheduled-jobs/not-running.mdx"
+import NotRunningWorkerMode from "../_sections/scheduled-jobs/not-running-worker-mode.mdx"
 
 export const metadata = {
   title: `Scheduled Job Not Running on Schedule`,
@@ -6,4 +7,46 @@ export const metadata = {
 
 # {metadata.title}
 
-<NotRunning />
+This guide helps you troubleshoot issues when a scheduled job in your Medusa application is not running, or running at unexpected times.
+
+## Confirm Job is Set Up Correctly
+
+Make sure that the scheduled job is set up correctly in your Medusa application. Check the following:
+
+1. The job is created under the `src/jobs` directory.
+2. The job exports an asynchronous function that performs the task. For example:
+
+```ts title="src/jobs/hello-world.ts"
+import { MedusaContainer } from "@medusajs/framework/types"
+
+export default async function greetingJob(container: MedusaContainer) {
+  const logger = container.resolve("logger")
+
+  logger.info("Greeting!")
+}
+```
+
+3. The job exports a `config` object that has the following properties:
+   - `name`: A unique name for the job.
+   - `schedule`: A string that holds a [cron expression](https://crontab.guru/) or an `interval` indicating the schedule to run the job.
+
+For example:
+
+```ts title="src/jobs/hello-world.ts"
+export const config = {
+  name: "greeting-every-minute",
+  schedule: "* * * * *",
+}
+```
+
+---
+
+## Job Not Running on Schedule
+
+<NotRunning />
+
+---
+
+## Confirm Worker Mode is Set Up Correctly
+
+<NotRunningWorkerMode />

www/apps/resources/app/troubleshooting/subscribers/not-working/page.mdx

@@ -0,0 +1,112 @@
+import NotRunningWorkerMode from "../../_sections/subscribers/not_running_workermode.mdx"
+import { CodeTabs, CodeTab } from "docs-ui"
+
+export const metadata = {
+  title: `Subscribers Not Working`,
+}
+
+# {metadata.title}
+
+This guide helps you troubleshoot issues when subscribers in your Medusa application are not running.
+
+## Confirm Event is Emitted
+
+Make sure that the event you're trying to listen to is actually being emitted. You can do this by adding a console log or using a debugger in the part of your code where the event is emitted.
+
+For example:
+
+<CodeTabs group="emit_event">
+  <CodeTab label="In a Workflow" value="workflow">
+```ts title="src/workflows/your-workflow.ts"
+import { 
+  createWorkflow,
+  transform
+} from "@medusajs/framework/workflows-sdk"
+import {
+  emitEventStep,
+} from "@medusajs/medusa/core-flows"
+
+const helloWorldWorkflow = createWorkflow(
+  "hello-world",
+  () => {
+    // ...
+
+    emitEventStep({
+      eventName: "custom.created",
+      data: {
+        id: "123",
+        // other data payload
+      },
+    })
+
+    transform({}, () => {
+      // For debugging purposes
+      console.log("Event emitted: custom.created")
+    })
+  }
+)
+```
+
+  </CodeTab>
+  <CodeTab label="Using Event Module's Service" value="service">
+
+```ts
+eventBusService_.emit({
+  name: "custom.event",
+  data: {
+    id: "123",
+    // other data payload
+  },
+})
+
+console.log("Event emitted: custom.event")
+```
+
+  </CodeTab>
+</CodeTabs>
+
+If the event is not being emitted, check the logic in your code to ensure that the event emission is correctly implemented.
+
+---
+
+## Confirm Subscriber is Set Up Correctly
+
+Make sure that your subscriber is correctly set up to listen to the event you're emitting. Check the following:
+
+1. The subscriber is created under the `src/subscribers` directory.
+2. The subscriber exports an asynchronus function that handles the event. For example:
+
+```ts title="src/subscribers/your-subscriber.ts"
+import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
+
+export default async function orderPlacedHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const logger = container.resolve("logger")
+
+  logger.info("Sending confirmation email...")
+
+  // ...
+}
+```
+
+3. The subscriber exports a configuration object with the correct event name. For example:
+
+```ts title="src/subscribers/your-subscriber.ts"
+export const config: SubscriberConfig = {
+  event: `order.placed`, // Confirm this name is correct
+}
+```
+
+If your subscriber is set up correctly, you'll see the following log in the terminal when the event is emitted:
+
+```bash
+info:    Processing order.placed which has 1 subscribers
+```
+
+---
+
+## Confirm Worker Mode is Set Up Correctly
+
+<NotRunningWorkerMode />

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

@@ -6567,7 +6567,7 @@ export const generatedEditDates = {
   "app/integrations/guides/payload/page.mdx": "2025-10-09T11:30:44.665Z",
   "references/js_sdk/admin/Client/methods/js_sdk.admin.Client.getToken/page.mdx": "2025-08-14T12:59:55.678Z",
   "app/commerce-modules/order/draft-orders/page.mdx": "2025-08-26T09:21:49.780Z",
-  "app/troubleshooting/scheduled-job-not-running/page.mdx": "2025-08-29T11:32:54.117Z",
+  "app/troubleshooting/scheduled-job-not-running/page.mdx": "2025-10-16T09:31:19.269Z",
   "app/troubleshooting/pnpm/page.mdx": "2025-08-29T12:21:24.692Z",
   "app/how-to-tutorials/tutorials/product-feed/page.mdx": "2025-10-02T10:24:52.283Z",
   "app/storefront-development/cart/manage-promotions/page.mdx": "2025-09-11T14:11:40.904Z",
@@ -6612,5 +6612,6 @@ export const generatedEditDates = {
   "app/nextjs-starter/guides/storefront-returns/page.mdx": "2025-09-22T06:02:00.580Z",
   "references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.views/page.mdx": "2025-09-18T17:04:59.240Z",
   "app/how-to-tutorials/tutorials/agentic-commerce/page.mdx": "2025-10-09T11:25:48.831Z",
-  "app/storefront-development/production-optimizations/page.mdx": "2025-10-03T13:28:37.909Z"
+  "app/storefront-development/production-optimizations/page.mdx": "2025-10-03T13:28:37.909Z",
+  "app/troubleshooting/subscribers/not-working/page.mdx": "2025-10-16T09:25:57.376Z"
 }

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

@@ -1487,6 +1487,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/storefront-pak-sc/page.mdx",
     "pathname": "/troubleshooting/storefront-pak-sc"
   },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/subscribers/not-working/page.mdx",
+    "pathname": "/troubleshooting/subscribers/not-working"
+  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/test-errors/page.mdx",
     "pathname": "/troubleshooting/test-errors"

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

@@ -166,6 +166,14 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
           "title": "Scheduled Job Not Running",
           "children": []
         },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "link",
+          "path": "/troubleshooting/subscribers/not-working",
+          "title": "Subscribers Not Working",
+          "children": []
+        },
         {
           "loaded": true,
           "isPathHref": true,

www/apps/resources/sidebars/troubleshooting.mjs

@@ -109,6 +109,11 @@ export const troubleshootingSidebar = [
         path: "/troubleshooting/scheduled-job-not-running",
         title: "Scheduled Job Not Running",
       },
+      {
+        type: "link",
+        path: "/troubleshooting/subscribers/not-working",
+        title: "Subscribers Not Working",
+      },
       {
         type: "link",
         path: "/troubleshooting/test-errors",