asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Shahed Nasser
2025-10-16 13:07:37 +03:00
committed by GitHub
parent ee1c77a01f
commit 4eb9628514
13 changed files with 308 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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

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

@@ -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

4
www/apps/book/generated/edit-dates.mjs
View File

@@ -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",

10
www/apps/book/public/llms-full.txt
View File

@@ -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

55
www/apps/resources/app/troubleshooting/_sections/scheduled-jobs/not-running-worker-mode.mdx Normal file
View File

@@ -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)

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

@@ -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)

55
www/apps/resources/app/troubleshooting/_sections/subscribers/not_running_workermode.mdx Normal file
View File

@@ -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)

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

@@ -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 />

112
www/apps/resources/app/troubleshooting/subscribers/not-working/page.mdx Normal file
View File

@@ -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 />

5
www/apps/resources/generated/edit-dates.mjs
View File

@@ -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"
}

4
www/apps/resources/generated/files-map.mjs
View File

@@ -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"

8
www/apps/resources/generated/generated-troubleshooting-sidebar.mjs
View File

@@ -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,

5
www/apps/resources/sidebars/troubleshooting.mjs
View File

@@ -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",