← all posts

PM2 cron_restart runs the script immediately: how to stop it

pm2 start --cron runs your job the moment you start it and again on every reload. We tested PM2 7.1.2 and found three ways to run it only at the cron time.

11 min read

You set up a nightly job at four in the afternoon:

pm2 start report.js --cron "0 6 * * *" --no-autorestart

It runs right away. Someone asked whether that’s intended in PM2 issue #5479 in 2022, and the answer was yes: --cron sets when PM2 restarts the app, not when it starts. In 2024 PM2 shipped autostart: false as the fix. We tested that too. With it, the job doesn’t run at four in the afternoon. It doesn’t run at six in the morning either.

Here is what PM2 7.1.2 actually does with a cron_restart job, start to finish, and three ways to get “run at 06:00 and only at 06:00”.

0 sfrom pm2 start --cron to the first run, whatever the schedule says
0 runsof a cron job with autostart: false, in PM2 7.1.2
exit 3shown by pm2 ls as stopped, same as a clean exit
SIGINTsent at every cron tick to a run that's still going

Short answer

PM2’s cron_restart restarts an app on a schedule. It assumes the app is already running, so pm2 start launches it straight away, and so do pm2 reload, pm2 restart all and, depending on what you saved, pm2 resurrect after a reboot. autostart: false is meant to prevent that, but in 7.1.2 an app added that way never starts at all, not even from its cron (#5831, open). The fix that works is a one-line clock check at the top of the script, plus --no-autorestart. If you’d rather have a scheduler that doesn’t run jobs at startup, use cron, a systemd timer, or RunWisp, an open-source cron replacement that ships as a single binary and keeps scheduled tasks separate from services. Keep PM2 for the web app, which it’s good at.

What you do What happens to a cron_restart job
pm2 start with --cron runs now, then at each cron time
…with default autorestart runs, exits, runs again, back-to-back, forever
…with autostart: false never runs, not even from the cron
pm2 reload <file>, pm2 restart all runs now
pm2 stop <app> stays registered; runs again at the next cron time
pm2 resurrect (reboot) runs now if it was online at pm2 save, else waits for cron
cron time while the last run is still going SIGINT to the old run, new run starts
job exits non-zero (--no-autorestart) shows stopped, like a success

How we tested

PM2 7.1.2, the current release, on Node 22 in a Debian container. The job is a shell script started with interpreter: "none": it prints a start line with its PID and the time, sleeps a set number of seconds, prints an end line and exits with a set code. It also traps SIGINT and SIGTERM so we could see which signal arrived. Most apps used cron_restart: "* * * * *" so a tick came every minute.

Why it runs immediately

PM2 is a process manager. Everything in it starts from the assumption that an app should be running. cron_restart is an extra: a croner job, registered per app, whose callback is PM2’s ordinary restart:

// lib/Worker.js, PM2 7.1.2
var job = Cron(pm2_env.cron_restart, function () {
    God.restartProcessId({ id: pm_id }, ...);
});

So pm2 start starts the app the way it starts any app, now. Our minute-schedule job started at 18:40:48 when we ran pm2 start, then at 18:41:00 and 18:42:00. With 0 6 * * * it’s the same: one run now, then one at 06:00.

Everything else that starts apps starts it too. We set cron_restart: "0 6 * * *" and ran each of these in turn, and each one ran the job again on the spot:

$ pm2 start ecosystem.config.js     # run 1
$ pm2 reload ecosystem.config.js    # run 2
$ pm2 restart all                   # run 3

That’s the one people hit after a deploy. A deploy script that does pm2 reload ecosystem.config.js for the web app also runs the nightly invoice job, at 2 pm.

autostart: false, the fix that doesn’t run

PM2 5.4.0 added autostart: false (and --no-autostart) in response to #5479. The configuration reference says what it should do with a cron:

The cron also fires when the app is stopped (or autostart: false), and starts it

We tried it:

// ecosystem.config.js
module.exports = {
    apps: [
        {
            name: "h-cronjob",
            script: "/w/job.sh",
            interpreter: "none",
            cron_restart: "* * * * *",
            autostart: false,
            autorestart: false,
        },
    ],
};

pm2 start added it as stopped, no run. So far so good. At the next minute PM2’s log shows the cron firing, and nothing else:

2026-11-17T18:48:00: PM2 log: [PM2] Deregistering a cron job on: 0
2026-11-17T18:48:00: PM2 log: [PM2][WORKER] Registering a cron job on: 0

No process, no log file, still stopped. pm2 restart h-cronjob and pm2 start h-cronjob both print ✓ and leave it stopped too. The reason is in lib/God.js: executeApp, which every start path goes through, returns early whenever the app’s autostart is false. The flag is kept on the app, so it can never be started, by the cron or by you. That’s #5831, open since May 2024, with a report against 7.1.2 from last week. Don’t use autostart: false for cron jobs until that’s fixed.

The rest of the lifecycle

Default autorestart turns a job into a loop

Without --no-autorestart, PM2 does what it does for any app that exits: it starts it again. Our 5-second job ran 18 times in 82 seconds, and pm2 ls showed online with 17 restarts. The cron restarts it at each tick on top of that. For a one-shot job you always want autorestart: false.

stop_exit_codes: [0] is the in-between: a clean exit stays stopped until the next tick, but per PM2’s docs a non-zero exit is restarted right away. A job that fails because a remote API is down will retry at full speed until it’s up.

A slow run gets interrupted at the next tick

The cron is a restart, so if the last run is still going, PM2 stops it first. A 90-second job on a one-minute schedule never finished:

start pid=301 18:42:33 code=0
got SIGINT pid=301 18:43:00
start pid=319 18:43:03 code=0
got SIGINT pid=319 18:44:00
start pid=332 18:44:03 code=0
got SIGINT pid=332 18:45:00

PM2 sends SIGINT, then SIGKILL after kill_timeout (1600 ms by default) if the process is still there. That’s cron’s overlap problem with the opposite answer: cron would have stacked copies, PM2 kills the old one. For a backup or an import that has outgrown its interval, that means it never completes, and nothing marks it as failed.

pm2 stop doesn’t stop the schedule

$ pm2 stop report
[PM2][WARN] App report stopped but CRON RESTART is still UP 0 6 * * *

The warning means it. In the source, only pm2 delete and the restart path deregister the cron (ActionMethods.js); stop doesn’t. A job we stopped by hand ran again at the next minute. To pause a job:

pm2 restart report --cron-restart 0   # drop the schedule (this runs it once more)
pm2 stop report

or pm2 delete report and add it back later.

After a reboot it depends on when you ran pm2 save

pm2 startup plus pm2 save brings apps back on boot with pm2 resurrect. What happens to a cron job depends on the status it had at the moment you saved:

  • online (you saved while it was running): starts immediately at boot.
  • stopped (it had already finished): stays stopped, the cron is registered, and it runs at the next cron time. This is the behaviour you want.
  • errored: starts immediately.

The usual sequence is pm2 start, then pm2 save straight after, while the job from that first immediate run is still going. So most cron jobs saved that way run at every boot. A job that finishes in a second may already be stopped by the time you type pm2 save, and doesn’t.

A failed run looks like a successful one

With autorestart: false, every exit is stopped. Our job exited 3:

$ pm2 describe report | grep -E 'status|restarts'
│ status            │ stopped │
│ restarts          │ 0       │

Identical to a run that exited 0. The code is in pm2 jlist as pm2_env.exit_code and in ~/.pm2/pm2.log as exited with code [3], for the latest run only. The job’s stdout from every run is appended to the same ~/.pm2/logs/<app>-out.log, with no marker between runs unless the job prints one. If you want to know a nightly job failed, the job has to tell you itself: see how to get alerted when a cron job fails.

Three ways to run it only on schedule

1. A clock guard in the script

No PM2 variable tells a cron start apart from any other start: the job sees cron_restart and restart_time in its environment, but restart_time stays 0 for cron starts of a stopped app. The clock does work. PM2’s cron fires at second 0 of the matching minute, so exit early unless it’s that minute:

#!/bin/sh
# report.sh: started by PM2 with --cron "0 6 * * *" --no-autorestart
[ "$(date +%H:%M)" = "06:00" ] || exit 0
exec node /srv/app/report.js

We tested it with a schedule one minute ahead: pm2 start printed skip 19:03:28, the cron printed run 19:04:00. In Node it’s if (new Date().getHours() !== 6 || new Date().getMinutes() !== 0) process.exit(0).

The guard and the cron line have to agree on the time zone: run both in the same TZ, and change both when you change the schedule. A start that’s delayed past the minute (a busy machine, a slow npm wrapper) is skipped, so keep the job itself as the script PM2 starts.

2. Keep it running and schedule inside

This is the PM2-native way: one long-running process with an in-process scheduler like croner or node-cron, started like any app. It never exits, so the start/stop questions go away, and the schedule’s first run waits for the clock. Two things to watch: run it as a separate fork-mode app with instances: 1, because in cluster mode every worker runs the schedule (that problem has its own post); and errors from the job are now your process’s to catch and report.

3. Give the job to a scheduler

cron or a systemd timer runs node /srv/app/report.js at 06:00 and doesn’t care how many times you redeployed. Keep PM2 for the web app and take the jobs out of ecosystem.config.js. Neither cron nor a timer runs a job at startup unless you ask (@reboot, Persistent=true), but you take on their gaps: cron’s silence, and getting NODE_ENV and the PATH to node right in its minimal environment.

In RunWisp: tasks and services are different things

RunWisp, our project, is an open-source cron replacement that ships as a single binary. It supervises long-running services too, but a scheduled job is a [tasks.*] entry with its own lifecycle:

[tasks.report]
cron = "0 6 * * *"
run  = "node /srv/app/report.js"
env  = { NODE_ENV = "production" }

We ran the same job (exit 3) under RunWisp 1.10.0 in the same container:

  • Starting the daemon doesn’t run it. A task runs at its cron time, or at startup only with run_on_start (true for every daemon start, "boot" for once per boot, like @reboot). If the machine was off at 06:00, catch_up runs the most recent missed run once at startup; set it to 0 to skip it.
  • Run now is separate from the schedule. runwisp run report (or the button in the Web UI) ran it once, printed the output, recorded failed, exit=3, and the shell got rc=3.
  • Pause means pause. runwisp pause report stops the schedule, and it stays paused across daemon restarts until you resume it. runwisp reload re-reads the config without running anything.
  • A slow run isn’t killed. By default a tick that arrives during a run is queued; skip and kill are options, and each is recorded in the run history.
  • Every run is a row with its exit code, duration and its own output.

The PM2 settings map like this:

PM2 RunWisp
cron_restart + autorestart: false [tasks.x] with cron =
autostart: false the default for tasks; autostart = false starts paused
pm2 stop + --cron-restart 0 runwisp pause x
pm2 restart x to run it now runwisp run x
stop_exit_codes: [0] on a worker [services.x] with restart = "on_failure"
kill_timeout (SIGINT, then SIGKILL) graceful_stop (SIGTERM, then SIGKILL); stop_signal to match

Where it doesn’t replace PM2: no Node cluster mode with a shared listening socket, no zero-downtime pm2 reload, no max_memory_restart, and it runs on one host. If your web app depends on those, keep it in PM2 and move only the scheduled jobs; the PM2 comparison goes through the trade-offs.

Which to pick

  • One or two jobs next to a PM2 app, and you’d rather not add anything: --no-autorestart and the clock guard. Remember pm2 stop doesn’t pause it.
  • The job shares code and connections with the app: an in-process scheduler in a single fork-mode app.
  • Several jobs, and you want to know when one fails: take them out of PM2 and into cron, a systemd timer or RunWisp, and get failure alerts and per-run history either way.

Related: node-cron running once per PM2 worker, what happens when a job outlasts its interval, and putting a timeout on a cron job. RunWisp’s source is on GitHub.

Common questions

Why does PM2 cron_restart run my script immediately?
Because cron_restart is a restart schedule for an app PM2 expects to be running, not a start time. pm2 start launches the app straight away like any other app, and the cron restarts it at each matching time. In PM2 7.1.2 the job also runs immediately on pm2 reload, pm2 restart all and pm2 resurrect, as long as it was running when you last ran pm2 save.
How do I make PM2 run a script only at the cron time?
PM2 has no working setting for it. The reliable fix is a guard at the top of the script that exits unless the clock matches the schedule, for example [ "$(date +%H:%M)" = "06:00" ] || exit 0 for a daily 06:00 job, together with --no-autorestart. PM2's cron fires at second 0, so the scheduled run passes the guard and every off-schedule start exits at once. Or keep the process running and schedule inside it with croner or node-cron, or move the job to cron, a systemd timer or another scheduler.
Does autostart: false work with cron_restart in PM2?
Not in PM2 7.1.2. The app is added as stopped and the cron fires on time, but nothing starts: PM2's executeApp returns early for any app whose autostart is false, so pm2 start, pm2 restart and the cron itself all leave it stopped with no log. This is issue #5831, open since May 2024, even though PM2's configuration docs say the cron starts such an app.
How do I stop a PM2 cron job?
pm2 stop isn't enough. It stops the current process, but the cron stays registered and starts the job again at the next matching time; the CLI warns 'stopped but CRON RESTART is still UP'. Remove the schedule with pm2 restart <app> --cron-restart 0 and then pm2 stop <app>, or pm2 delete <app>, which deregisters the cron with the app.
Why does PM2 show my failed cron job as stopped?
With autorestart: false, PM2 marks any exit as stopped, whatever the exit code. In our test a job that exited 3 showed stopped with 0 restarts, exactly like one that exited 0. The code is only in pm2 jlist (pm2_env.exit_code) and in ~/.pm2/pm2.log, and only for the latest run; earlier runs' codes aren't kept.
Is there a scheduler that doesn't run a cron job at startup?
RunWisp, an open-source cron replacement that ships as a single binary, keeps scheduled jobs and long-running services as separate kinds. A task with cron = "0 6 * * *" runs at 06:00 and not when the daemon starts, unless you set run_on_start. Pausing a task survives restarts, every run is recorded with its exit code, and a run that would overlap is queued rather than killed. Its limits: it isn't a Node process manager, with no cluster mode, shared listening socket or zero-downtime reload, so many people keep PM2 for the web app and move only the jobs.
  1. Cron MAILTO not working? Where cron's email actually goes

    We sent cron mail on Debian, Ubuntu, Fedora and Alpine and traced where it went: /var/mail, syslog, a refused port 25 or nowhere. Then made msmtp deliver it.

  2. What happens when a cron job takes longer than its interval

    We ran jobs longer than their interval under cron, cronie, systemd timers, supervisord and RunWisp. cron stacks copies; systemd runs them back to back.

Get started
GPL 3.0 · no accounts · free to self-host

Start in 30 seconds. Ship on your terms.

A single Go binary. If it doesn't earn the disk space, rm it. No account, no signup, no catch.

Install in 30 seconds
curl -fsSL https://get.runwisp.com | sh