# node-cron Not Running? 9 Causes and Fixes for node-cron 4

By Dan Ochoa · Published 2026-11-16 · Updated 2026-11-16
Canonical: https://cronradar.com/blog/node-cron-not-running

> Why a node-cron 4 task does not run or runs too often: process exits, serverless, PM2 cluster mode, time zones, bad expressions, overlap, and missed runs.

**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](https://cronradar.com/blog/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:

```js
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](https://github.com/node-cron/node-cron/blob/master/README.md).

## 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 `unref` option (default `false`) turns that off; with `unref: 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_INSTANCE` for each cluster instance, starting at `0`:

  ```js
  const 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 `distributed` option.** Current releases document a `distributed` option that runs a task on one instance per fire across a fleet. It requires a `name` (the coordination key) and a run coordinator; read the [scheduling options](https://nodecron.com/scheduling-options) for the coordinators available before relying on it. Instances that aren't elected emit `execution: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](https://cronradar.com/blog/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:

```js
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](https://cronradar.com/blog/cron-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-2` in 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:

```js
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:

```js
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:

```js
// 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:

```js
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](https://cronradar.com/blog/prevent-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](https://nodecron.com/migrating-from-v3):

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

```bash
npm install cronradar
```

```js
const 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 `warning` to `critical` and 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](https://docs.cronradar.com/integrations/node) and the [Node.js page](https://cronradar.com/nodejs) 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.
