[Documentation Issue] Job Schedulers `immediately` repeat option is unclear.

[Chee7ah]

trafficstars

Documentation: https://docs.bullmq.io/guide/job-schedulers/repeat-options#immediately

When you use the every option in BullMQ, it schedules jobs based on fixed time intervals, which might seem a bit counterintuitive initially. ... For example, if you set the job to repeat monthly, normally it would wait to start until the first second of the next month. If you add the job mid-month, it would not start until the beginning of the following month. Using immediately ensures the first instance of the job runs as soon as it’s added, bypassing the wait until the scheduled interval begins.

Then we have the example:

await myQueue.upsertJobScheduler(
  'immediate-job',
  {
    every: 86400000, // once a day
    immediately: true, // execute the first one immediately
  },
  {
    name: 'instant-job',
    data: { message: 'Immediate start' },
  },
);

---

Running the above code results in the Using option immediately with every does not affect the job's schedule. Job will run immediately anyway. warning, coming from here: https://github.com/taskforcesh/bullmq/blob/7a37f0998fd809ba31244c0da6db010ad34098d3/src/classes/job-scheduler.ts#L62-L66

This is clearly contradicting what the documentation says.

What I wanted to do is to schedule a repeating job that runs now and then 24 hours later and another 24 hours later and so on. It seems like having the below code accomplishes this goal (at least running this, my job ran immediately), even though according to the documentation, this would first run at the first second of the next day.

await myQueue.upsertJobScheduler(
  'my-job',
  {
    every: 86400000, // once a day
  }
);

---

1. Is my experimental understanding correct, that every causes the job to run now and repeats after every interval?
2. If so, can the documentation be updated to reflect the actual behavior?

[manast]

We deprecated "immediately" on repeat recently but have not yet updated the documentation, thank you for posting this to remind me. The current behaviour is as if immediately is always true, if you need a different behaviour you can use the much more flexible cron expressions or custom expressions.

[robincsamuel]

• Is my experimental understanding correct, that every causes the job to run now and repeats after every interval?

@manast Could you please clarify this as well? As per the documentation, every should be running every x seconds. For example, if it's 60000, then the start of every minute. However, for me it's working like an interval; when the job is added at 00:00:15, the next execution is at 00:01:15 instead of 00:01:00.

[manast]

@robincsamuel The documentation states precisely that, so AFAICS it is correct. If you need the jobs to repeat at given points in time line at every starting minute you can use cron expressions.

[robincsamuel]

@manast The documentation reads,

When you use the every option in BullMQ, it schedules jobs based on fixed time intervals, which might seem a bit counterintuitive initially. For instance, if you set an interval of 2000ms, jobs will be triggered at every even second—such as 0, 2, 4, 6, 8 seconds, and so on. This means the scheduling aligns with the clock, regardless of when you actually added the job.

Reference: https://docs.bullmq.io/guide/job-schedulers/repeat-options#immediately

[manast]

@robincsamuel yes, you are right, but thats the old behaviour if you scroll a bit you can find this:

[clemens]

I think the documentation for repeated/scheduled jobs is still a fair bit unclear, especially with regards to the pattern option and how this behaves in various situations (and consequently whether or not these behaviors are then as expected). Let me outline a few examples:

• I would generally expect that a new job isn't immediately created when using pattern. Otherwise, there will be situations where I'm defining jobs with e.g. pattern: "0 * * * * " (every hour) and if the server happens to start any time between 2 hour marks, there would be an unexpectedly small gap between jobs, which could be confusing to downright problematic.
• When passing startDate and pattern, I'd expect this to be respected. Say, I have { pattern: "0 * * * * ", startDate: new Date("2025-06-01") }, I'd expect the job to be first run on 1 June 2025 at 00:00 – not immediately (see above) and also not at the next full hour.
• While one could of course simply think about it a bit, a bit of documentation for "odd" cases could come in helpful – e.g. think about { pattern: "0 0 * 6 *", startDate: new Date("2025-07-01") }. This job generally runs at midnight every day in June, but due to the start date, the first time it will actually run is 1 June 2026 at midnight.

What do you think?

[manast]

@clemens All the points you wrote are true when using pattern. The default behaviour of immediately is just for the "every" option.

[clemens]

Would you accept pure documentation PRs? Then I'd be happy to take a stab at adding a distinct page for the pattern option.