Schedules
A schedule is a stored record that makes one job for each tick of its timing: a cron rule in a time zone, or a fixed every period.
await queue.upsertSchedule('digest', {
cron: '0 7 * * *',
tz: 'Europe/Berlin',
template: { data: { to: 'team@example.com' } },
})- Schedules live in the store, so every pod sees the same ones.
QueueandProducerboth manage them. - They fire only on a pod that runs the queue's scheduler: every pod with a worker on the queue, from its first
process()until its last worker closes, or a pod that calledstartScheduler(). A producer never fires one. Scheduler options are in Queue options. - One job per tick, however many pods run a scheduler. Ticks are judged by store time; pod clocks never matter. A tick fires within about
tickMsof its time. - After downtime, the missed ticks collapse into one job for the oldest missed tick. The schedule then goes on from its grid.
queue.pause()holds the jobs back but does not stop schedules from making them. UsepauseSchedule(key).- A running scheduler keeps the process alive until it stops or the queue closes.
Methods
| Method | Returns |
|---|---|
upsertSchedule(key, def) | Promise<UpsertResult<T>> |
getSchedule(key) | Promise<Schedule | null> |
listSchedules(opts?) | Promise<{ schedules: Schedule[]; nextCursor: string | null }> |
pauseSchedule(key) | Promise<Schedule> |
resumeSchedule(key) | Promise<Schedule> |
deleteSchedule(key) | Promise<boolean> |
nextRuns(key, n?) | Promise<number[]> |
previewSchedule(timing, n?) | Promise<number[]> |
const { action } = await queue.upsertSchedule('digest', { every: '1h', template: { data: { to: 'team@example.com' } } })
const schedule = await queue.getSchedule('digest')
const { schedules, nextCursor } = await queue.listSchedules({ state: 'paused', limit: 50 })
await queue.pauseSchedule('digest')
await queue.resumeSchedule('digest')
const deleted = await queue.deleteSchedule('digest')
const next = await queue.nextRuns('digest', 3)
const preview = await queue.previewSchedule({ cron: '30 2 * * 1-5', tz: 'Europe/Berlin' })keyis a non-empty string of at most 200 UTF-8 bytes. The job idsched:<key>:<tick>must also fit the store's id limit.upsertSchedulecreates or replaces the schedule. It is safe to call from every pod at start-up.UpsertResultis{ schedule, action }, withactionone of'created','updated','unchanged'(the same definition is stored) or'stale'(a higherversionis stored, and nothing was written).getSchedulereturnsnullfor an unknown key.listSchedulesreturns one page in key order. Options:limit1 to 1000 (default100),cursor(thenextCursorof the page before), andstate('active'or'paused'). Withstate, a page may hold fewer thanlimitwhilenextCursoris set.pauseSchedulestops the ticks.resumeSchedulestarts them again from the next tick after now; missed ticks are not caught up. Both throwScheduleNotFoundErrorfor an unknown key.deleteSchedulereturnsfalsewhen there was none. Jobs it already made are left alone.nextRunsreturns the nextntick times after store now, in epoch ms, also for a paused schedule. It throwsScheduleNotFoundErrorfor an unknown key.previewSchedulereturns up tontick times of a timing after store now. It stores nothing.nis 1 to 100 (default5).- A bad definition, key or timing throws one
InvalidOptionErrorlisting every problem. Issues about the timing carry areason:'bad-cron','bad-timezone','no-occurrence','bad-interval'or'bad-overlap'. - Events:
scheduleFired,scheduleSkippedandscheduleQueuedon the pod that fired;schedulePaused,scheduleResumedandscheduleDeletedon the object that called. See Events.
ScheduleDefinition
ScheduleDefinition<D> is a ScheduleTiming plus these keys.
| Name | Type | Default | Meaning |
|---|---|---|---|
cron | string | none | A cron rule. Give cron or every, not both. See Cron. |
tz | string | 'UTC' | The IANA time zone of cron, such as 'Europe/Berlin'. Only with cron. |
every | Duration | none | A fixed period, 1 s to 100 years. See Every. |
template | ScheduleTemplate<D> | required | What each job is made of. See ScheduleTemplate. |
version | number | none: unversioned | A positive whole number. A stored definition with a higher version is never replaced by a lower one. |
overlap | OverlapPolicy | 'skip' | What a tick does while the schedule's previous job has not finished. See Overlap. |
maxQueued | number | 10 | Ticks kept waiting under overlap: 'queue', 1 to 1000. Only with 'queue'. |
await queue.upsertSchedule('digest', { cron: '0 7 * * 1-5', template: { data: { to: 'team@example.com' } } })
await queue.upsertSchedule('digest', { cron: '0 7 * * *', tz: 'America/New_York', template: { data: { to: 'team@example.com' } } })
await queue.upsertSchedule('poll', { every: '30s', template: { data: { to: 'ops@example.com' } } })
await queue.upsertSchedule('digest', { every: '1d', template: { name: 'digest', data: { to: 'team@example.com' } } })
await queue.upsertSchedule('digest', { every: '1d', version: 3, template: { data: { to: 'team@example.com' } } })
await queue.upsertSchedule('report', { every: '1h', overlap: 'allow', template: { data: { to: 'team@example.com' } } })
await queue.upsertSchedule('report', { every: '1h', overlap: 'queue', maxQueued: 3, template: { data: { to: 'team@example.com' } } })Give a version for rolling deploys. A pod that still has an older definition answers 'stale' and logs one warning, instead of overwriting the newer one.
ScheduleTiming
ScheduleTiming is { cron: string; tz?: string } or { every: number | string }. previewSchedule takes it on its own.
Cron
Five fields. There is no seconds field: use every below one minute.
| Field | Values | Names |
|---|---|---|
| minute | 0-59 | |
| hour | 0-23 | |
| day of month | 1-31 | |
| month | 1-12 | JAN-DEC |
| day of week | 0-7 (0 and 7 are Sunday) | SUN-SAT |
- Each field is a comma-separated list of
*,*/n,a,a-bora-b/n. Names are case-insensitive and work as range ends.L,W,#,?anda/nare not supported. - Aliases:
@yearly(0 0 1 1 *),@monthly(0 0 1 * *),@weekly(0 0 * * 0),@daily(0 0 * * *),@hourly(0 * * * *). - When both day of month and day of week are restricted, a day matches if either one matches:
0 0 13 * 5is every 13th and every Friday. Otherwise both must match. A field that starts with*, such as*/2, is not restricted. tzmust be an IANA zone name or'UTC'. Abbreviations and offsets such as'EST','CET','GMT'or'+02:00'are refused with'bad-timezone'. Times are computed from store now with the zone rules of the pod's Node.js, so run the same Node.js version on every pod.- A rule must match some date within 9 years:
0 0 30 2 *is refused with'no-occurrence'.0 0 29 2 *fires on leap days only.
Daylight saving: an hour field of * or with a step (*/2, 0-10/5) follows elapsed time. Any other hour field follows the clock.
| Change | Elapsed-time rule | Clock-time rule |
|---|---|---|
| A local time is skipped (spring forward) | Nothing extra fires. | Fires once, at the end of the gap. |
| A local time repeats (fall back) | Fires in both passes. | Fires once, in the first pass. |
In Europe/Berlin on 2026-03-29 (02:00 jumps to 03:00):
| Expression | Fires at (UTC) |
|---|---|
30 2 * * * | 01:00Z (the end of the gap) |
*/30 2 * * * | 01:00Z, once |
0 * * * * | every full hour; 23 runs that day |
In Europe/Berlin on 2026-10-25 (03:00 falls back to 02:00):
| Expression | Fires at (UTC) |
|---|---|
30 2 * * * | 00:30Z only |
0 * * * * | every full hour, both 00:00Z and 01:00Z |
Every
Whole milliseconds, or a string with unit ms, s, m, h or d ('30s', '2h'). From 1 second to 100 years. There is no w unit.
Ticks sit on a fixed grid, anchor + k × period, anchored at store now when the schedule is created. A late fire never moves the next tick.
await queue.previewSchedule({ every: '15m' }, 3)ScheduleTemplate
ScheduleTemplate<D> is what each fired job is made of.
| Name | Type | Default | Meaning |
|---|---|---|---|
data | D | required | The job data. Serialized and checked once, at upsert: against maxPayloadBytes and the queue filter (operation 'schedule'). |
name | string | none: an unnamed job | The job name. |
opts | add options | none | Any add option except id, delay, runAt, onDuplicate, uniqueWhile, singletonKey and idempotencyKey. |
await queue.upsertSchedule('digest', { every: '1d', template: { data: { to: 'team@example.com' } } })
await queue.upsertSchedule('digest', { every: '1d', template: { name: 'digest', data: { to: 'team@example.com' } } })
await queue.upsertSchedule('digest', { every: '1d', template: { data: { to: 'team@example.com' }, opts: { maxAttempts: 5, priority: 10 } } })The queue's defaultJobOptions apply when each job is made, so changing them changes later jobs. The template's own opts win.
Fired jobs
- Each fired job has the id
sched:<key>:<scheduledFor>andrunAtset toscheduledFor. job.scheduleis{ key, scheduledFor }on a fired job andnullon others. See Job and context.
queue.process(async (job) => {
if (job.schedule) console.log(`tick ${job.schedule.scheduledFor} of ${job.schedule.key}`)
})Overlap
OverlapPolicy decides what a tick does while the schedule's previous job is waiting, delayed or active.
| Value | What the tick does |
|---|---|
'skip' | Dropped. scheduleSkipped fires with reason: 'overlap'. The default. |
'queue' | Kept in a backlog of at most maxQueued ticks, run one job at a time in tick order. scheduleQueued fires. Past the cap the tick is dropped with reason: 'backlog-full'. |
'allow' | Fires anyway. |
Schedule
Schedule<D> is a stored schedule as the methods return it.
| Field | Type | Meaning |
|---|---|---|
key | string | The key. |
namespace | string | The namespace. |
queue | string | The queue name. |
kind | 'cron' | 'every' | Which timing it uses. |
cron | string, optional | The cron rule. |
tz | string, optional | The time zone. |
everyMs | number, optional | The period, in ms. |
anchorAt | number, optional | Start of the every grid, in store time. |
template | { name: string | null; data: D; opts: Record<string, unknown> } | The template, data read back. |
overlap | OverlapPolicy | The overlap policy. |
maxQueued | number | The backlog cap. |
paused | boolean | true while paused. |
nextRunAt | number | The next tick, in store time. |
lastFiredFor | number | null | The tick of the last job made. |
lastJobId | string | null | The id of the last job made. |
queuedTicks | number[] | Ticks in the 'queue' backlog. |
runCount | number | Jobs made so far. |
definitionHash | string | A hash of the definition, used to answer 'unchanged'. |
definitionVersion | number | The stored version. |
formatVersion | number | The record format. |
createdAt | number | When the schedule was first stored, in store time. |
updatedAt | number | When the schedule was last changed, in store time. |
rev | number | The revision, raised on each write. |
createdAt | number | When it was created, in store time. |
updatedAt | number | When it was last written, in store time. |
const s = await queue.getSchedule('digest')
if (s) console.log(s.kind, s.paused, new Date(s.nextRunAt).toISOString(), s.runCount)Health
health() warns SCHEDULER_STALE when this pod's running scheduler has not finished a loop turn in 5 × tickMs, and NO_SCHEDULER_RUNNING when the queue has unpaused schedules and no live worker runs a scheduler. See Health and metrics.