Heroku Scheduler Best Practices for Production
Your Heroku Scheduler jobs run in production, and on most days they do exactly what you expect. Every now and then, though, runs go wrong for different reasons. A customer gets the same reminder twice. A nightly sync doesn't happen, and nobody notices until the end of the week. A cleanup job stops halfway, and the last line in its log is Heroku stopping it.
None of these is a bug. They're the cases Heroku Scheduler doesn't promise to handle, and an app that runs jobs for years needs to be ready for all of them.
The Heroku Scheduler best practices in this post come down to one rule: Heroku Scheduler doesn't promise to run a job exactly once, so write every job to do the right thing whether a run happens on time, twice, or not at all. That takes six habits: make jobs safe to run twice, let the next run catch up, finish well inside the interval, shut down cleanly, stay under the one-off dyno limit, and monitor every run.
What Heroku Scheduler promises, and what it doesn't
Heroku Scheduler starts your job in a one-off dyno every 10 minutes, every hour, or every day, but it doesn't promise that each of those starts happens exactly once. The Dev Center article on Heroku Scheduler is plain about it:
Scheduler is a free add-on with no guarantee that jobs will execute at their scheduled time, or at all:
- In very rare instances, a job may be skipped.
- In very rare instances, a job may run twice.
Heroku gives no figure for "very rare". A job on the 10-minute frequency runs 144 times a day, though, so rare cases add up over the life of an app.
A one-off dyno also never restarts on its own, so a run that stops partway through stays stopped until the job's next scheduled run. For jobs that are a critical part of your app, Dev Center points to a custom clock process instead, which trades a free add-on for a dyno that runs all the time and scheduling code you maintain.
Make every job safe to run twice
Let the database hand each piece of work to exactly one run, so the job is idempotent: running it twice has the same effect as running it once. A Heroku Scheduler job can run twice in two ways: the rare double run, and a brief overlap when a run lasts its whole interval. Heroku stops a run when it reaches its interval, and because there is some jitter in when that stop happens, the old dyno and the next run's dyno can overlap for a brief time.
A database gives you two tools for that. A transaction groups several changes into one unit of work: either all of them are saved, or none of them are. If the program fails halfway, the database undoes what it had already changed, so a piece of work is never left half done. A lock lets a transaction reserve the data it's working on, so nobody else can claim that data until the transaction ends.
Together they make a job idempotent in three steps, whatever language and database you use:
- Work on one piece at a time, and let the database hand it out. Each run asks for the next piece of work that's due and not yet done, and locks it. Another run that asks at the same moment passes over the locked piece instead of waiting for it, and takes the next one.
- Claim it, do it, and mark it done in one transaction. The run commits only after the piece is marked done. If the run fails or dies before the commit, the database keeps none of it, and the piece is due again.
- Give anything outside the database an idempotency key. A transaction can't take back an email that went out or a card that was charged. Build a key from the piece of work, such as its ID, and pass it to your email or payment provider: one that supports idempotency keys returns the first result for a key it has seen instead of acting twice.
Two runs going at once now share the work instead of repeating it, because each piece belongs to whichever run claimed it first. A run that dies halfway through a piece leaves it for the next run, which does it again with the same key, so the outside world sees it once. For a job that creates records, such as a daily summary, a unique constraint on what makes each record unique does the same: the second run's insert finds the record already there and skips it.
Some work can't be split into pieces, like a full resync of an external system. For that, add a guard so only one run works at a time: a lock that only one run can hold. A run that can't take the lock logs a line such as "previous run still active" and exits with status 0, because an overlap isn't a failure. A dyno that vanishes can leave its lock held for a while, so the log line matters: a run of skips in your logs means a stuck lock, not a busy job. Keep the work itself idempotent too, because a run can still stop between two writes.
Let the next run catch up on a missed one
Treat the next scheduled run as the recovery for a skipped one. That only works if the job decides what to do from state, not from the clock. A job built as in the last section already does: it asks for everything that's due and not yet done, not for "this hour's work". A run that comes after a skipped one picks up both runs' work without any special handling.
Keep that state in your database, never in a file. Each dyno's filesystem is ephemeral, and anything written to it is discarded the moment the dyno stops.
The frequency sets how much a miss costs you: an hourly job that works from state loses an hour, and a daily job loses a day. If a day's delay would hurt, run the job more often and let each run do whatever has become due.
Keep each run well inside its interval
Heroku Scheduler is for short work, and the Dev Center article on Heroku Scheduler says so directly:
Scheduled jobs are meant to execute short running tasks or enqueue longer running tasks into a background job queue. Anything that takes longer than a couple of minutes to complete should use a worker dyno to run.
That matters because Heroku stops each run at its interval: a 10-minute job gets about 10 minutes and a daily job about 24 hours, so a job that uses most of its interval is the one that risks being stopped partway.
If a job has to run longer than a few minutes, give each run a time budget well under the interval, for example 8 minutes of a 10-minute job, and stop picking up work once it's spent. Work that can't fit belongs in a queue: the Heroku Scheduler job enqueues it, and a worker dyno processes it. The trade-off is cost, because a worker accrues usage for as long as it runs, not only while there's work.
Shut down cleanly when Heroku stops a run
The interval isn't the only thing that ends a run partway. Heroku can also end a one-off dyno for these reasons:
- Hardware: the dyno manager restarts dynos as needed, for example when it detects a fault in the underlying hardware, and for a one-off dyno that ends the run.
- Relocation: a dyno moved to another server may get no SIGTERM at all.
- Memory: a dyno that vastly exceeds its memory quota (error R15) is killed with SIGKILL, which can't be caught.
When Heroku stops a run, it sends SIGTERM first. The SIGTERM goes to every process in the dyno, can arrive more than once, and is followed by SIGKILL for anything still running 30 seconds later.
So build each run to stop well, in this order:
- Make it crash-safe. A job that commits each piece of work in its own transaction loses at most the piece in progress, even to a SIGKILL, and the next run redoes it.
- Make it signal-aware. When the SIGTERM arrives, set a flag, and check that flag before the job takes the next piece, so the run ends between two pieces instead of in the middle of one. The handler has to be safe to run twice, because the signal can arrive more than once.
- Check the time budget in the same place. Before each piece, the job asks two questions: has Heroku asked me to stop, and is my budget spent? A yes to either ends the run cleanly.
- Report the stop. A run that ends early because of a SIGTERM exits with a non-zero status, by convention 143, so the stop shows up as a stop and not as a clean finish.
Stay under the one-off dyno limit
Every Heroku Scheduler run is a one-off dyno, and each app can run only so many one-off dynos at once, depending on the dyno type:
| Dyno type | Concurrent one-off dynos per app |
|---|---|
| Eco | 1 |
| Basic | Up to 50 |
| Standard | Up to 50 |
| Performance | Up to 5 |
| Private | Up to 5 |
| Shield | Up to 5 |
A Private Space has its own default cap too: five concurrent one-off Private or Shield dynos for the whole space. These limits assume an account with an established payment history. When the app is at its limit, a scheduled run can't start a dyno, and Heroku documents no alert for that case.
Eco is where this bites first, because its one slot is shared. A heroku run console left open on an Eco app is a one-off Eco dyno, and so is a slow run of another job. Before you open a console, check what's already running. With a console open, the output looks like this example:
$ heroku ps --app example-app
=== run: one-off processes (1)
run.1234 (Eco): up 2026/10/22 01:58:41 +0000 (~ 2m ago): bash
While that console is open, a job due at 2:00 AM UTC can't start a dyno. Eco has one more catch for production jobs. Scheduler runs draw on the account's Eco dyno hours, and when those run out, every Eco dyno on the account sleeps for the rest of the month. Move apps that are critical to Basic dynos.
On any tier, count the worst case. Daily jobs are set in UTC, so jobs that share a start time come due together, on top of the long runs still going and the consoles your team opens. Stagger start times so the peak stays well under the limit.
More Heroku Scheduler best practices for production
Five smaller details catch jobs that pass every test:
- Secrets: on the Common Runtime, Heroku expands config vars in the command before it logs it, so a secret written into the Heroku Scheduler command ends up in your logs. Read config vars inside the script instead.
- Deploys: a release doesn't stop a running one-off dyno, so a run started before a deploy finishes on the old code. Make schema changes that the previous release can live with.
- Maintenance mode: Heroku Scheduler jobs can still run while your app is in maintenance mode, so give a job that has to pause a switch of its own.
- Database connections: every run that's going at once opens its own connections, and smaller database plans allow only a few. Give each job a small pool.
- Container Registry: if you deploy with Container Registry, every Heroku Scheduler job runs from the
webimage, so its command must exist there.
Make every job easy to monitor
Out of the box, your Heroku Scheduler jobs run blind. Application Metrics charts only the dynos in your app's formation, such as web and worker, so the one-off dynos that run your jobs never appear in it. Threshold Alerting watches only web response times and failed web requests. Nothing from Heroku tells you that a job failed, was stopped at its interval, ran long, or never ran, so make each run leave its own record. Four records cover it:
- Exit status: make every error end the run with a non-zero status, so a failed run looks failed, and report a stop the same way.
- Start and end lines: log one line when the run starts and one when it ends, with what it did, such as how many pieces of work it finished. Turn off any log buffering in your runtime, so the lines arrive while the run is going.
- Log history: Heroku keeps only the last 1,500 log lines for an app, which a busy app passes quickly. Add a log drain or a logging add-on to keep last week's runs.
- Last success: have each run write the time it finished to the database, and have something outside the job, such as your app's health check, flag that time when it's older than the interval. Logs can't show a run that never started; a stale timestamp can.
Start monitoring Heroku Scheduler in one click
Heroku Scheduler Monitor tells you when one of the cases described above happens. It reads Heroku platform data for the detached scheduler one-off dynos that Heroku Scheduler starts, and notifies you when a monitor opens an alert:
| When a job | Heroku Scheduler Monitor |
|---|---|
| Fails with a non-zero exit status | Job Failure monitor |
| Is stopped at its interval or forced to exit | Job Interruption monitor (an interruption, not a failure) |
| Runs longer than you expect | Job Execution Time monitor, at a threshold you set |
| Overlaps with another run of itself | Job Concurrency monitor, at a threshold you set |
| Has many runs going at once | Scheduler Concurrency monitor, on the total number of scheduler dynos |
| Never starts, including when the app was at its limit | Skip detection |
Alerts tell you when something goes wrong. The dashboard shows you how your jobs run the rest of the time, which is the view Application Metrics never gives you for one-off dynos. It keeps 7 days of execution data and plots it in four charts:
- Events: the lifecycle events of each run, so you can follow any run from start to finish.
- Execution Time: summary metrics for how long runs take, so you see a job creeping toward its interval before Heroku stops it.
- Throughput: runs by exit status, so successes, failures and interruptions sit side by side.
- Concurrency: how many one-off dynos run at the same time, so you see overlaps and how close you are to the limit.
The add-on needs no config var, code change, or redeploy. It watches, plots and alerts, and doesn't interfere with your Heroku Scheduler jobs in any way. See the full feature list, or find Heroku Scheduler Monitor in the Heroku Elements Marketplace.
Next steps
Before you trust a changed job in production, run it manually with the same dyno size and time limit as a scheduled run, and watch it finish inside its interval.
Originally published:
