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

2025-10-16 13:07:37 +03:00
1 parent ee1c77a01f
commit 4eb9628514
@@ -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)
@@ -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)
@@ -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)
@@ -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 />
@@ -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 />