node-cron Not Running? 9 Causes and Fixes for node-cron 4
Contents
A node-cron task runs only while the Node.js process that scheduled it is alive and its event loop is free at the due time. Most "node-cron isn't running" reports come down to a process that exited, restarted, or was frozen (serverless), a schedule read in a different time zone than intended, or an event loop busy enough that node-cron counted the run as missed. The opposite complaint, running too often, is almost always several processes each running their own copy.
This guide covers node-cron 4 (4.6.0 was the latest release on npm when checked on November 16, 2026), which requires Node.js 20 or later. Version 4 was a rewrite and changed options that v3 code still passes; cause 9 covers those. For node-cron compared with other schedulers, see Node.js schedulers compared.
Check These First#
| Symptom | Likely cause |
|---|---|
| Never runs in production, runs locally | Serverless platform (2) or process exits (1) |
| Stopped after a crash or deploy, until restart | Process restarted or crashed (1, 7) |
| Runs 2, 4, or 8 times each time | PM2 cluster mode or several replicas (3) |
| Runs at the wrong hour, or shifts with DST | Time zone (4) |
| Never runs, no error | Expression means something else (5), or v4 options (9) |
| Some runs skipped, warnings in the log | Missed executions from a blocked event loop (6) |
| Runs pile up and the job gets slower | Overlapping runs (8) |
| Whole process dies, every task stops | An unhandled promise rejection (7) |
A quick check that the task exists and when it will run next:
const cron = require('node-cron')
const task = cron.schedule('0 2 * * *', () => console.log('nightly'), {
name: 'nightly-report',
timezone: 'UTC',
})
console.log(task.getStatus(), task.getNextRun())getStatus() returns 'idle', 'running', 'stopped', or 'destroyed', and getNextRun() returns the next Date or null. If the next run is null or not the time you expected, the problem is the schedule, not the process. These methods are in the node-cron README.
1. The Process Exited or Restarted#
node-cron keeps tasks in memory. Nothing is stored, so a task exists only from the moment cron.schedule runs until the process ends. When the process exits, crashes, or is restarted by PM2, systemd, Docker, or a deploy, the schedule is gone until the code runs again, and any due time that passed in between is simply skipped.
Things that end the process without anyone noticing:
- A one-shot script. If the script that schedules tasks is run by cron or a CI step and expected to stay up, it exits when its runner stops it. node-cron's timer normally keeps the process alive, but the
unrefoption (defaultfalse) turns that off; withunref: true, a process with nothing else to do exits. process.exit()elsewhere, for example in a startup check, an error handler, or a CLI library.- An out-of-memory kill or a crash (cause 7). A supervisor restarts the process, the task is scheduled again, and the runs during the gap never happen.
Log at startup when each task is scheduled, and log the process start time. A process that restarts every few hours under PM2 or Kubernetes explains runs that "sometimes" don't happen.
2. The Platform Freezes or Stops Idle Processes#
Serverless and scale-to-zero platforms run your code only while handling a request. On AWS Lambda, Vercel functions, Netlify functions, Cloud Functions, and Cloud Run or Azure Container Apps scaled to zero, there's no long-lived process to hold a timer. A task scheduled during one invocation fires only if another invocation happens to be running at the due time, which in practice means never.
Use the platform's own scheduler to call your code instead: EventBridge Scheduler for Lambda, Vercel Cron Jobs, Cloud Scheduler, or a Kubernetes CronJob. node-cron belongs in a process that stays up: a VM, a container with minimum replicas of at least one, or a dedicated worker.
3. PM2 Cluster Mode or Replicas Run One Copy Each#
node-cron has no idea other processes exist. PM2 in cluster mode (-i max or exec_mode: 'cluster') starts one process per instance, and each schedules every task, so a 4-instance cluster runs each job four times. The same happens with several containers, pods, or dynos.
Options, from simplest:
-
Schedule in one instance only. PM2 sets
NODE_APP_INSTANCEfor each cluster instance, starting at0:JavaScriptconst cron = require('node-cron') if (process.env.NODE_APP_INSTANCE === undefined || process.env.NODE_APP_INSTANCE === '0') { cron.schedule('*/15 * * * *', syncInventory, { name: 'sync-inventory' }) } async function syncInventory() { console.log('Syncing inventory') }If instance 0 dies, PM2 restarts it, so this keeps one copy without a second process type. It doesn't help across several machines.
-
Run the scheduler as its own process, in PM2 fork mode or as a single-replica deployment, separate from the web cluster.
-
Use node-cron's
distributedoption. Current releases document adistributedoption that runs a task on one instance per fire across a fleet. It requires aname(the coordination key) and a run coordinator; read the scheduling options for the coordinators available before relying on it. Instances that aren't elected emitexecution:skipped.
During a rolling deploy, old and new processes overlap, and both may run a due task. Make tasks safe to run twice (idempotent scheduled jobs).
4. The Time Zone Isn't the One You Meant#
Without the timezone option, node-cron evaluates the expression in the system time zone. Containers and most cloud VMs default to UTC, so 0 9 * * * that ran at 09:00 on a laptop in Chicago runs at 09:00 UTC in production.
Set the zone explicitly with an IANA name:
cron.schedule('0 9 * * 1-5', sendStandupReminder, {
name: 'standup-reminder',
timezone: 'America/Chicago',
})With a zone that observes daylight saving time, a run scheduled inside the spring-forward gap or the repeated fall-back hour needs care; cron and daylight saving time covers both. Scheduling in UTC avoids the problem.
5. The Expression Means Something Else#
node-cron accepts five fields, or six with a leading seconds field. That optional seconds field is the most common surprise: 0 */5 * * * * is every five minutes at second 0, but */5 * * * * * (six fields) is every five seconds.
Other rules from the README:
- Day of week is standard cron, 0 or 7 for Sunday, not Quartz's 1-for-Sunday.
- It supports
L,L-n,W,LW,#,<weekday>L, and?, which many other cron implementations don't, so an expression copied out of node-cron may not work elsewhere. - Inverted ranges wrap:
22-2in the hour field means 22, 23, 0, 1, 2.
Validate expressions that come from configuration before scheduling them, and fail startup loudly if one is invalid:
const cron = require('node-cron')
const expression = process.env.REPORT_SCHEDULE ?? '0 2 * * *'
if (!cron.validate(expression)) {
throw new Error(`Invalid REPORT_SCHEDULE: ${expression}`)
}6. Runs Were Skipped as Missed#
node-cron 4 sleeps until the next matching time instead of polling every second. If the timer fires late, because the event loop was blocked by synchronous work, a long garbage-collection pause, or a laptop or VM that was suspended, node-cron compares the delay with missedExecutionTolerance (1,000 ms by default). Within the tolerance, the run still executes. Beyond it, the run is reported as missed and skipped, a warning is logged, and the task emits execution:missed.
A process that spends seconds at a time in synchronous CPU work, such as parsing a large file or hashing in a loop, skips scheduled runs this way. Fix the blocking work, or raise missedExecutionTolerance for that task. Don't silence it with suppressMissedWarning without handling the event, or skipped runs vanish from the logs too:
const task = cron.schedule('* * * * *', collectMetrics, { name: 'collect-metrics' })
task.on('execution:missed', () => {
console.warn('collect-metrics missed a scheduled run')
})
async function collectMetrics() {
console.log('Collecting metrics')
}7. An Unhandled Rejection Killed the Process#
Errors thrown by the task function, including a rejected promise it returns, are caught by node-cron 4 and reported through the execution:failed event and lastRun(), which returns { date, error }. The task keeps its schedule.
Promises the task starts but doesn't return or await aren't covered. If one rejects with no handler, it's an unhandled rejection, and since Node.js 15 the default is to crash the process. Every task in the process stops until something restarts it, which looks like cause 1:
// Wrong: the promise isn't awaited, so a rejection is unhandled and crashes Node.js.
cron.schedule('0 * * * *', () => {
refreshCache()
})
// Right: node-cron receives the promise and reports a failure through execution:failed.
cron.schedule('0 * * * *', async () => {
await refreshCache()
})
async function refreshCache() {
throw new Error('Cache backend unavailable')
}Listen for failures so they reach your logs and alerts:
task.on('execution:failed', () => {
console.error('Task failed', task.name, task.lastRun()?.error)
})8. Runs Overlap#
By default node-cron starts a run on schedule even if the previous one is still running. A job every minute that sometimes takes three minutes ends up with several copies running against the same data, each slower than the last.
Set noOverlap: true to skip a run while the previous one is executing. The skipped run emits execution:overlap, so log it; frequent overlaps mean the schedule is too tight for the work. Across processes, noOverlap does nothing; see cause 3 and preventing overlapping cron jobs.
9. v3 Options That v4 Doesn't Have#
Code written for node-cron 3 can run under v4 and behave differently. From the v3 migration guide:
| v3 | v4 |
|---|---|
{ scheduled: false } to create a stopped task |
Removed. cron.schedule starts the task; use cron.createTask(...) and call task.start() later |
{ runOnInit: true } |
Removed. Call task.execute() after scheduling |
{ recoverMissedExecutions: true } |
Removed. Missed runs emit execution:missed and aren't replayed |
task.now() |
task.execute(), which returns a promise |
task-done event |
execution:finished and execution:failed |
cron.getTasks() keyed by name |
A Map keyed by task id |
| Node.js 6 and later | Node.js 20 and later |
The scheduled: false row is the dangerous one: a task meant to start later starts immediately. And code that relied on runOnInit to run a job at boot no longer runs it until the first scheduled time.
Get Alerted When a Run Doesn't Happen#
Every cause above that matters most ends with a process that isn't running the task: exited, frozen, crashed, or never deployed. node-cron's events can't report that, because they come from the process that stopped. Catching it takes a check outside the process that knows when each run is due.
CronRadar's Node SDK (cronradar 0.1.1 on npm) wraps the task function. There's no node-cron integration or auto-discovery; you wrap each task you want monitored, with its key and schedule:
npm install cronradarconst cron = require('node-cron')
const cronradar = require('cronradar')
const SCHEDULE = '0 2 * * *'
const nightlyReport = cronradar.wrap(
'nightly-report',
async () => {
await buildNightlyReport()
},
{ schedule: SCHEDULE },
)
const task = cron.schedule(SCHEDULE, nightlyReport, {
name: 'nightly-report',
timezone: 'UTC',
noOverlap: true,
})
task.on('execution:failed', () => console.error('nightly-report failed', task.lastRun()?.error))
async function buildNightlyReport() {
console.log('Building the nightly report')
}Set CRONRADAR_API_KEY in the process's environment. The wrapper reports a start before the function runs, a completion when it resolves, and a failure with the error's message when it rejects, then re-throws the original error, so node-cron still emits execution:failed. Requests time out after five seconds, and monitoring errors never reach your task. The first report creates the monitor from schedule, and a deleted monitor re-creates itself.
What gets caught:
- No run: when no start arrives by the expected time plus the grace period, the monitor goes from
warningtocriticaland alerts by email, Slack, webhook, Discord, or PagerDuty. That covers causes 1, 2, 6, and 9, and a process crashed by cause 7. - Failure: a rejected or thrown task alerts immediately.
- Stuck: a start with no finish, such as a run cut off by a restart, is flagged as stuck.
- Duplicates: with cause 3, every copy reports; CronRadar records each run but doesn't alert on extra runs, so fix duplicates with the options in cause 3.
Send five-field cron. A six-field expression with a seconds field other than 0 has no five-field form, so it can't be monitored on its exact schedule; a task every 30 seconds, for example, can only be expected once a minute (* * * * *). CronRadar evaluates schedules in the application's time zone, set in its settings (UTC if unset), so match it to the timezone option. The Node.js integration guide and the Node.js page cover setup. Use a separate CronRadar application and key per environment.
Frequently Asked Questions#
Why does node-cron run my job multiple times?#
More than one process scheduled it. PM2 cluster mode, several containers, or several replicas each run their own node-cron, and each runs every task. Schedule in one instance, for example when NODE_APP_INSTANCE is 0 under PM2, run the scheduler as a separate single process, or use node-cron's distributed option with a coordinator.
Does node-cron work on Vercel, Netlify, or AWS Lambda?#
Not reliably. Those platforms run code only while handling a request, so there's no process to hold node-cron's timer between invocations. Use the platform's scheduler, such as Vercel Cron Jobs or EventBridge Scheduler, to call an endpoint or function at the scheduled time.
What time zone does node-cron use?#
The system time zone, unless you pass the timezone option with an IANA name such as America/New_York. Containers and most servers default to UTC, which is why a schedule that worked locally runs at a different hour in production.
Does node-cron catch errors in async tasks?#
node-cron 4 catches errors thrown by the task function and rejections of the promise it returns, and reports them through the execution:failed event and lastRun(). A promise the task starts without awaiting or returning isn't covered; if it rejects unhandled, Node.js crashes the process by default.
Why doesn't scheduled: false work in node-cron 4?#
The scheduled and runOnInit options were removed in v4. cron.schedule starts the task as soon as it's created. To create a task without starting it, use cron.createTask(expression, fn, options) and call task.start() when you're ready.
Put this guide to work
Connect your Node.js job to monitoring
Follow the current integration guide, check the release limitations, and verify a real run and alert delivery.
npm installs cronradar 0.1.2. It reports the jobs you wrap and does not discover jobs automatically.