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”.
pm2 start --cron to the first run, whatever the schedule saysautostart: false, in PM2 7.1.2pm2 ls as stopped, same as a clean exitShort 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(truefor every daemon start,"boot"for once per boot, like@reboot). If the machine was off at 06:00,catch_upruns the most recent missed run once at startup; set it to0to 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, recordedfailed,exit=3, and the shell gotrc=3. - Pause means pause.
runwisp pause reportstops the schedule, and it stays paused across daemon restarts until youresumeit.runwisp reloadre-reads the config without running anything. - A slow run isn’t killed. By default a tick that arrives during a run is queued;
skipandkillare 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-autorestartand the clock guard. Rememberpm2 stopdoesn’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?
How do I make PM2 run a script only at the cron time?
Does autostart: false work with cron_restart in PM2?
How do I stop a PM2 cron job?
Why does PM2 show my failed cron job as stopped?
Is there a scheduler that doesn't run a cron job at startup?
Read next
-
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.
-
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.