diff --git a/www/apps/book/app/learn/fundamentals/events-and-subscribers/page.mdx b/www/apps/book/app/learn/fundamentals/events-and-subscribers/page.mdx
index c6016d19b4..da973ea5c3 100644
--- a/www/apps/book/app/learn/fundamentals/events-and-subscribers/page.mdx
+++ b/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
diff --git a/www/apps/book/app/learn/fundamentals/scheduled-jobs/page.mdx b/www/apps/book/app/learn/fundamentals/scheduled-jobs/page.mdx
index 10cd18522b..6cddc0b2e1 100644
--- a/www/apps/book/app/learn/fundamentals/scheduled-jobs/page.mdx
+++ b/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
diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs
index 0e573c01df..85667d6345 100644
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/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",
diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt
index e4357f2764..ac505118c5 100644
--- a/www/apps/book/public/llms-full.txt
+++ b/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
diff --git a/www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running-worker-mode.mdx b/www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running-worker-mode.mdx
new file mode 100644
index 0000000000..081e42ec6a
--- /dev/null
+++ b/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).
+
+
+
+If you're a Cloud user and this issue is happening on your deployed Medusa application, contact support for assistance.
+
+
+
+### 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)
\ No newline at end of file
diff --git a/www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running.mdx b/www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running.mdx
index a5d9a7ceb7..d865949c19 100644
--- a/www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running.mdx
+++ b/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)
\ No newline at end of file
diff --git a/www/apps/resources/app/troubleshooting/_sections/subscribers/not_running_workermode.mdx b/www/apps/resources/app/troubleshooting/_sections/subscribers/not_running_workermode.mdx
new file mode 100644
index 0000000000..7b7e19aab1
--- /dev/null
+++ b/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).
+
+
+
+If you're a Cloud user and this issue is happening on your deployed Medusa application, contact support for assistance.
+
+
+
+### 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)
\ No newline at end of file
diff --git a/www/apps/resources/app/troubleshooting/scheduled-job-not-running/page.mdx b/www/apps/resources/app/troubleshooting/scheduled-job-not-running/page.mdx
index 722d6b0803..a8383ce3f8 100644
--- a/www/apps/resources/app/troubleshooting/scheduled-job-not-running/page.mdx
+++ b/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}
-
\ No newline at end of file
+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
+
+
+
+---
+
+## Confirm Worker Mode is Set Up Correctly
+
+
\ No newline at end of file
diff --git a/www/apps/resources/app/troubleshooting/subscribers/not-working/page.mdx b/www/apps/resources/app/troubleshooting/subscribers/not-working/page.mdx
new file mode 100644
index 0000000000..957efd443c
--- /dev/null
+++ b/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:
+
+
+
+```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")
+ })
+ }
+)
+```
+
+
+
+
+```ts
+eventBusService_.emit({
+ name: "custom.event",
+ data: {
+ id: "123",
+ // other data payload
+ },
+})
+
+console.log("Event emitted: custom.event")
+```
+
+
+
+
+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
+
+
\ No newline at end of file
diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs
index 34bbb9a30c..e7d5d132d9 100644
--- a/www/apps/resources/generated/edit-dates.mjs
+++ b/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"
}
\ No newline at end of file
diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs
index f2dfa01fec..e5fc7596c7 100644
--- a/www/apps/resources/generated/files-map.mjs
+++ b/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"
diff --git a/www/apps/resources/generated/generated-troubleshooting-sidebar.mjs b/www/apps/resources/generated/generated-troubleshooting-sidebar.mjs
index 7effccb1c7..ebc2012ed4 100644
--- a/www/apps/resources/generated/generated-troubleshooting-sidebar.mjs
+++ b/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,
diff --git a/www/apps/resources/sidebars/troubleshooting.mjs b/www/apps/resources/sidebars/troubleshooting.mjs
index 0c09a85c21..272911ec37 100644
--- a/www/apps/resources/sidebars/troubleshooting.mjs
+++ b/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",