Scheduled Job Not Running on Schedule

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:

src/jobs/hello-world.ts
1import { MedusaContainer } from "@medusajs/framework/types"2
3export default async function greetingJob(container: MedusaContainer) {4  const logger = container.resolve("logger")5
6  logger.info("Greeting!")7}

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 or an interval indicating the schedule to run the job.

For example:

src/jobs/hello-world.ts
1export const config = {2  name: "greeting-every-minute",3  schedule: "* * * * *",4}

Job Not Running on Schedule#

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#

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#

If you prioritize running your scheduled jobs consistently over precise timing, consider using a scheduled job interval instead.

By using an interval, the job will run after a defined duration, regardless of the system's state.

For example, to run a scheduled job every minute, you can set the interval to 60000 milliseconds (1 minute):

Code
1import { MedusaContainer } from "@medusajs/framework/types"2
3export default async function greetingJob(container: MedusaContainer) {4  const logger = container.resolve("logger")5
6  logger.info("Greeting!")7}8
9export const config = {10  name: "greeting-every-minute",11  schedule: {12    interval: 60000, // 1 minute13  },14}

Additional Resources#

• Set Interval for Scheduled Jobs

Confirm Worker Mode is Set Up Correctly#

If your scheduled job isn't running at all, it may be because your Medusa application is not running in worker mode.

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 guide.

For example, you should have the following configuration in your medusa-config.ts file:

medusa-config.ts
1module.exports = defineConfig({2  projectConfig: {3    workerMode: process.env.WORKER_MODE || "shared",4    // ...5  },6  // ...7})

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:

medusa-config.ts
1module.exports = defineConfig({2  projectConfig: {3    workerMode: "shared", // or don't set it at all4    // ...5  },6  // ...7})

Additional Resources

• Worker Mode