This guide covers APScheduler 3.11.3, the current release on PyPI (checked October 30, 2026); the 4.0 line is still pre-release there, at 4.0.0a6. Server behavior is checked against the source of Gunicorn 26.2.0, Uvicorn 0.54.0, Flask 3.1.3 with Werkzeug 3.1.9, and Django 6.1.2. For APScheduler's general failure modes and events, see Python scheduler monitoring; for duplicates caused by crontab, systemd, or Kubernetes, see why a cron job runs twice.

Count the Schedulers First

Log the process every time a scheduler starts. start() dispatches EVENT_SCHEDULER_STARTED once it is running (base.py), so add the listener before calling it:

import logging
import os

from apscheduler.events import EVENT_SCHEDULER_STARTED

log = logging.getLogger("scheduler")


def log_scheduler_start(event):
    log.warning("APScheduler started: pid=%s parent=%s", os.getpid(), os.getppid())


scheduler.add_listener(log_scheduler_start, EVENT_SCHEDULER_STARTED)
scheduler.start()

Then compare the duplicate runs:

The last two have one scheduler and are covered under when one scheduler runs the job twice.

Why Every Web Worker Runs Its Own Scheduler

BackgroundScheduler.start() starts a thread named APScheduler in the calling process and returns (background.py). Each process that runs that code gets its own scheduler object, its own job store, and its own executor. Nothing connects them. The APScheduler 3.x FAQ is direct about the shared-database version of this:

Sharing a persistent job store among two or more processes will lead to incorrect scheduler behavior like duplicate execution or the scheduler missing jobs, etc. This is because APScheduler does not currently have any interprocess synchronization and signalling scheme...

The user guide adds: "Job stores must never be shared between schedulers." With the default in-memory store, every worker holds a full private copy of every job, so each one runs all of them. Moving to SQLAlchemyJobStore doesn't fix this. It replaces independent copies with schedulers racing over the same rows.

The FAQ entry on web applications says to "First read through the previous section" (faq.rst), which is the job store entry above. How many processes you get depends on the server.

Gunicorn

Without --preload, each worker loads your WSGI app after it has been forked (workers/base.py), so code at import time, or in an app factory, runs once per worker. -w 4 means four schedulers. The worker count defaults to the WEB_CONCURRENCY environment variable when it is set (config.py), so a platform that sets it can turn one scheduler into several without a change to your command.

Worker restarts start schedulers too. With --max-requests, a worker restarts after that many requests (config.py), and its replacement loads the app again, starting a new scheduler as the old one exits with its worker.

Uvicorn

uvicorn app:app --workers 4 starts four worker processes from a spawn multiprocessing context (_subprocess.py), and each one imports the app in its own server (server.py). As with Gunicorn, the worker count defaults to WEB_CONCURRENCY when you don't pass --workers (config.py). Moving scheduler.start() from module level into a FastAPI or Starlette lifespan handler doesn't help: the lifespan is created in that same per-worker server, right after the app loads.

With --reload or more than one worker, the Uvicorn parent process doesn't load the app at all; only the children do (main.py). Under uvicorn --reload, you therefore have one scheduler at a time, replaced on each reload.

What --preload Does to the Scheduler Thread

With --preload, Gunicorn loads the app in the master process before forking any workers (arbiter.py), a setting its docs describe as a way to "save some RAM resources as well as speed up server boot times" (config.py). A scheduler started at import now starts its thread in the master. Workers are created with os.fork() (arbiter.py), and POSIX specifies that the child of a multi-threaded process contains "a replica of the calling thread" only (fork).

The result looks like a fix and isn't one:

• Jobs run only in the master, because only the master has a scheduler thread. The duplicates disappear by accident.
• Each worker holds a copy of the scheduler with no thread behind it. Its state was copied from the master, so it still reports itself as started. A job a request handler adds with add_job() goes into that worker's copy, where nothing will run it. With a persistent store, the row reaches the database, but the master's scheduler isn't notified, per the FAQ above.
• Every fork is a fork of a multi-threaded process. Since Python 3.12, os.fork() raises a DeprecationWarning when it detects other threads, and the docs say "it has never been safe to mix threading with os.fork() on POSIX platforms" (os.fork). Gunicorn forks again every time it replaces a worker.

Treat --preload as a memory setting. If the scheduler belongs in the master, it belongs in its own process instead.

Development Reloaders Start a Second Scheduler

These cases run two schedulers on a laptop even when production runs one.

Flask: flask run --debug and app.run(debug=True)

flask run --debug turns the reloader on, because --reload defaults to the debug flag (cli.py). The command loads your app before it starts the server (cli.py). Werkzeug's reloader then starts a new interpreter with the same arguments and WERKZEUG_RUN_MAIN=true, waits for it, and starts another when a file change makes it exit with code 3 (_reloader.py). That child loads the app again.

So a scheduler started at import or in create_app() runs in the parent for the whole session and in the child, with the child's copy replaced on every reload. app.run(debug=True) behaves the same way, because use_reloader defaults to the debug setting (app.py).

Werkzeug exposes the check as is_running_from_reloader(), which tests that environment variable (serving.py). --debug sets FLASK_DEBUG early so that factories can read it (cli.py), and the app's DEBUG config starts from that value (sansio/app.py):

from flask import Flask
from werkzeug.serving import is_running_from_reloader


def create_app():
    app = Flask(__name__)
    # ... register blueprints and jobs ...
    if not app.debug or is_running_from_reloader():
        scheduler.start()
    return app

Under flask run --debug, or with FLASK_DEBUG=1 set, this skips the reloader parent and nothing else. It makes the scheduler wait for the reloader in debug mode, so flask run --debug --no-reload starts no scheduler at all. It does nothing about Gunicorn workers, where app.debug is false and every worker passes the check.

The guard doesn't work with app.run(debug=True). get_debug_flag() reads only FLASK_DEBUG (helpers.py), and app.run() sets app.debug from its debug argument only when it is called (app.py), after create_app() has returned. The factory sees app.debug as false in both processes, and both start a scheduler. flask run --reload without --debug fails the same way. For app.run(debug=True), set FLASK_DEBUG=1 in the environment before the script starts, or pass use_reloader=False.

Django: runserver and AppConfig.ready()

Unless you pass --noreload, manage.py runserver runs django.setup() in the parent process first (management/__init__.py), which calls every AppConfig.ready(). The autoreloader then runs the command again in a child with RUN_MAIN=true (autoreload.py, autoreload.py), and ready() runs again there. A scheduler started in ready() runs twice.

It also starts in places you didn't intend. Django's docs warn that ready() "will run during startup of every management command" (applications), so migrate, shell, and collectstatic each start a scheduler too, one that lasts as long as the command does.

Checking os.environ.get("RUN_MAIN") == "true" skips the parent, but RUN_MAIN is an internal name in django.utils.autoreload (autoreload.py), not a documented setting, and it isn't set under Gunicorn at all. The durable fix is to take the scheduler out of ready() and start it from a management command run as its own process, the dedicated scheduler process below. Django cron monitoring gives the same advice for django-apscheduler.

The Fixes, and What Each Costs

Every fix trades duplicate runs for a different failure: zero schedulers. Decide which you would rather detect.

A Dedicated Scheduler Process

This is the FAQ's workaround: "Run the scheduler in a dedicated process" (faq.rst). Use BlockingScheduler, which the user guide recommends "when the scheduler is the only thing running in your process" (userguide.rst), in an entry point such as python -m myapp.scheduler, deployed beside the web service. Remove every start() call from the web app. Python scheduler monitoring has a complete worker of this kind.

What it costs:

• One more process to deploy, supervise, and restart. If it's down, nothing runs and nothing errors.
• No more add_job() from request handlers. The web app can't reach the scheduler's in-memory jobs. The FAQ suggests a remote access mechanism such as RPyC, gRPC, or an HTTP server; many teams define jobs in code instead.
• It must stay at one copy. Scaling the scheduler service to two replicas brings the duplicates back. Distributed cron covers why a one-replica Deployment can briefly be two during a rolling update.

One Web Worker Wins a Lock

Keep the scheduler inside the web app, and let only the worker that gets an exclusive lock start it. On a single host, fcntl.flock with LOCK_NB fails immediately with an OSError instead of waiting (fcntl):

import fcntl
import logging
import os

log = logging.getLogger("scheduler")
_lock_file = None  # Keep the file open: closing it releases the lock.


def start_scheduler_if_first(scheduler, lock_path):
    global _lock_file
    lock_file = open(lock_path, "w")
    try:
        fcntl.flock(lock_file, fcntl.LOCK_EX | fcntl.LOCK_NB)
    except OSError:
        lock_file.close()
        log.info("pid=%s: another process runs the scheduler", os.getpid())
        return False
    _lock_file = lock_file
    scheduler.start()
    log.info("pid=%s: running the scheduler", os.getpid())
    return True

Call it where you used to call scheduler.start(). The kernel releases the lock when every descriptor for that open file is closed, including when the process exits (flock(2)), so a crashed holder can't leave a stale lock.

What it costs:

• One scheduler per host, not per deployment. Each machine or container has its own lock file. Two app servers mean two schedulers.
• The scheduler lives and dies with one web worker. When Gunicorn restarts the holder, for --max-requests or a timeout, the scheduler goes with it. It comes back only when a newly booted worker takes the lock. Workers that lost the race at startup don't try again.
• Take the lock after the fork. Under --preload, this code runs once, in the master, and flock(2) notes that descriptors duplicated by fork(2) "refer to the same lock," so every worker shares the master's.

Across hosts, PostgreSQL's pg_try_advisory_lock(key bigint) does the same thing: it "will either obtain the lock immediately and return true, or return false without waiting" (advisory lock functions). A session-level advisory lock "is held until explicitly released or the session ends" (advisory locks), so the winning worker must keep that connection open for its whole life, outside any pool that might close or reuse it. If the connection drops, the lock is released while the scheduler thread keeps running, and the next worker to boot can win it too.

Run One Web Worker

A single web worker also gives you one scheduler per host: -w 1 for Gunicorn, --workers 1 for Uvicorn. Pass the count explicitly, because without the flag both servers use WEB_CONCURRENCY when it is set (Gunicorn, Uvicorn). The price is serving all traffic from one process, and the scheduler still restarts whenever that worker restarts.

When One Scheduler Runs the Job Twice

max_instances, coalesce, and misfire_grace_time act inside one scheduler. None of them can see another process.

max_instances (default 1) is counted in a dictionary held by each executor (executors/base.py, submit check). It stops a slow run from overlapping the next one in the same scheduler. Four workers with max_instances=1 can still run four copies at once.

Catch-up after a restart is the same-PID, back-to-back pattern. It needs a job that stayed in a persistent store while the scheduler was down and wasn't added again at startup: adding it again with replace_existing=True overwrites the stored row with a next run time computed from now (base.py). Even then, the 3.x default coalesce=True (base.py) submits only the latest missed time (base.py), so a burst of runs means coalesce=False together with a long misfire_grace_time or misfire_grace_time=None. Missed runs after downtime covers the defaults and whether catching up is what you want.

Copies of the job are the pattern that grows with each deploy. A job added without an id gets a random one (job.py). In a persistent store, adding it at startup therefore adds a new row each time, which the user guide flags in bold: you "MUST define an explicit ID for the job and use replace_existing=True or you will get a new copy of the job every time your application restarts!" (userguide.rst). Add both, then remove the old copies, which scheduler.get_jobs() lists under their random IDs.

Even with one scheduler, a run can repeat after a crash or a lock that changes hands. Idempotent scheduled jobs shows how to make a second run of the same occurrence do nothing.

Report Each Run to CronRadar

Python SDK connections are temporarily unavailable (Python integration), so each job reports with HTTP check-ins. HTTP check-ins don't discover jobs automatically; give each job its own monitor key and its real schedule. Keep the API key in a CRONRADAR_API_KEY environment variable from your deployment's secret store, with a separate CronRadar application and key for each environment.

Python scheduler monitoring has the standard-library check-in helper, which uses HTTP Basic auth with the key as username and an empty password, a five-second timeout, and logs monitoring errors instead of raising them. It also has a wrapper that reports a start, then a completion or a failure, and re-raises the job's exception. For duplicate runs, change only how that wrapper builds its run_id: include the host and PID, so each run in the monitor's history shows which process ran it.

import os
import socket
import uuid


def new_run_id():
    # At most 128 characters; identifies the process, never the job's data.
    return f"{socket.gethostname()[:60]}-{os.getpid()}-{uuid.uuid4().hex[:12]}"

In that post's monitored_backup(), replace run_id = uuid.uuid4().hex with run_id = new_run_id(). The wrapper already sends the same run_id with the start and with the completion or failure, and the API accepts up to 128 characters for it (API reference).

If one expression feeds both CronTrigger.from_crontab() and the monitor's schedule, which CronRadar reads as five-field cron in UTC (schedule syntax), avoid numeric weekdays: from_crontab() in APScheduler 3.x treats 0 as Monday, while standard cron treats it as Sunday (cron trigger).

What this shows, and what it doesn't:

• Duplicates are visible, not alerted. CronRadar records every run it receives and doesn't alert on extra runs. Each run_id appears as its own run in the monitor's history, with its Execution ID, so four runs at the same scheduled time from four PIDs is the per-worker pattern above.
• Zero schedulers is alerted. This is the failure every fix above introduces: a dedicated process that didn't restart, or a lock holder that was recycled. No start arrives, the monitor shows warning once the scheduled time passes, and critical after the grace period, with an alert by email, Slack, webhook, Discord, or PagerDuty.
• A failed run alerts immediately. fail records the result failed and opens an incident.

Don't send an Idempotency-Key derived from the scheduled time to collapse the duplicates. A repeated key returns the original ping without reapplying state (API reference), so the dashboard would show one run while the job still ran twice.

Frequently Asked Questions

Why does my APScheduler job run once per Gunicorn worker?

Without --preload, each Gunicorn worker loads your app after it is forked, so a scheduler started at import or in an app factory starts once per worker: -w 4 means four schedulers. Without -w, the count comes from WEB_CONCURRENCY when it is set. Log os.getpid() when the scheduler starts to count them.

How do I run APScheduler with Gunicorn and multiple workers?

Run the scheduler outside Gunicorn, as one BlockingScheduler process, which is what the APScheduler FAQ recommends. If it must live in the web app, start it only in the worker that wins an exclusive lock, and accept that it restarts whenever that worker does.

Does gunicorn --preload fix duplicate APScheduler jobs?

It hides them. The scheduler thread starts in the master, and forked workers don't get a copy of it, so jobs run only in the master. Each later fork is a fork of a multi-threaded process, which Python's documentation calls unsafe, and a job added from a worker goes into a scheduler copy with no thread to run it.

Why does APScheduler run twice with flask run --debug?

The debug reloader loads your app in a parent process, then again in a child process started with WERKZEUG_RUN_MAIN=true. With flask run --debug, start the scheduler only when not app.debug or is_running_from_reloader(), or run a dedicated scheduler process. That check fails under app.run(debug=True), where app.debug is still false when the factory runs; there, set FLASK_DEBUG=1 before the script starts or pass use_reloader=False.

Does max_instances=1 stop duplicate runs?

Only inside one scheduler. Each process counts its own running instances, so it stops overlap of a slow run but not a second process starting the same job.

This guide covers the Better Stack Terraform provider 0.22.4, the current release on the Terraform Registry (checked October 30, 2026), and Better Stack's hosted heartbeats as its documentation, API reference, and pricing page described them on that date. It compares heartbeat features only, not Better Stack's uptime checks, status pages, or telemetry products. For other options, see Sentry Crons vs a dedicated cron monitor, Dead Man's Snitch vs CronRadar, and Uptime Kuma push monitors.

How a Better Stack Heartbeat Is Configured

In the dashboard you go to Heartbeats → Create heartbeat, give it a name, set Expect a heartbeat every to the task's frequency, set the grace period, "the extra time allowed before an incident is raised if the heartbeat is missed," choose on-call escalation settings, and then copy the secret URL from the heartbeat's detail page (heartbeat guide).

The same settings are fields of the Create a heartbeat API, POST https://incidents.betterstack.com/api/v2/heartbeats with a bearer token:

None of these fields is a schedule. The heartbeat knows how often to expect a request and how long to wait, nothing about which days or times the job runs.

Pending, Up, Down, and Validating

A new heartbeat stays Pending until its first request arrives. The guide says "the monitoring period begins from the first heartbeat received, and incidents are only raised after the expected frequency and grace period have elapsed" (heartbeat guide). A heartbeat for a job that was never deployed therefore never starts its monitoring period, and the guide describes no alert for that case.

After that, the API's status field reports up when requests arrive on time, down when one didn't, validating when requests arrive on time again and the incident waits to be resolved, maintenance inside the maintenance window, and paused (Get a single heartbeat). An incident stops alerting other team members once someone acknowledges it (acknowledging).

Heartbeats in Terraform

The provider's betteruptime_heartbeat resource takes the same settings except metadata and exposes the heartbeat URL as the computed url attribute (resource docs). The provider reads its token from BETTERUPTIME_API_TOKEN when api_token is omitted (provider.go):

terraform {
  required_providers {
    betteruptime = {
      source  = "BetterStackHQ/better-uptime"
      version = "0.22.4"
    }
  }
}

# The API token comes from the BETTERUPTIME_API_TOKEN environment variable.
provider "betteruptime" {}

resource "betteruptime_heartbeat" "nightly_backup" {
  name   = "Nightly database backup"
  period = 86400 # one request a day
  grace  = 3600  # up to an hour late before an incident
}

output "nightly_backup_heartbeat_url" {
  value     = betteruptime_heartbeat.nightly_backup.url
  sensitive = true
}

In 0.22.4 the url attribute isn't marked sensitive (resource_heartbeat.go), so mark any output that exposes it sensitive = true, which redacts it in the CLI's apply output. Terraform still stores it in state, and terraform output -raw prints it in plain text (Terraform docs), which is how you'd read it to install on the job host.

The Heartbeat URL Is the Secret

A heartbeat URL has the form https://incidents.betterstack.com/api/v1/heartbeat/<HEARTBEAT_TOKEN>, and the guide calls it a secret URL. The documented requests carry no other credential, so anyone who has the URL can mark the job as having run or report it failed. Keep it out of crontab lines, scripts in version control, and job logs: store it in a file readable only by the job's account, or in your platform's secret store.

The guide documents three requests (heartbeat guide):

• The URL itself records a heartbeat. The guide's example is a plain curl at the end of the job.
• The URL plus /fail explicitly reports a failure.
• The URL plus the exit code, with the job's output sent as the request body, reports a failure with both, "to help diagnose the failure."

It documents no start request and no run duration, so a run that hangs sends nothing and shows up as a missed heartbeat once the period and grace pass.

This wrapper sends the plain request after a successful run, and the exit code with the output's last 10 KB after a failed one. The guide states no size limit for the body; the 10 KB cut is this script's choice. Each request gives up after five seconds, a failed request is ignored, and the script exits with the job's own code:

#!/bin/sh
# /opt/backup-betterstack.sh: run the backup, then report to a Better Stack heartbeat.
# The file holds only the heartbeat URL and is readable only by this account.
heartbeat_url=$(cat /etc/betterstack/nightly-backup.url 2>/dev/null)

report() {
  [ -n "$heartbeat_url" ] || return 0
  curl --fail --silent --show-error --max-time 5 --output /dev/null "$@" || true
}

output=$(/opt/backup.sh 2>&1)
rc=$?
printf '%s\n' "$output"

if [ "$rc" -eq 0 ]; then
  report "$heartbeat_url"
else
  # The exit code in the path reports a failure; the body carries the output.
  printf '%s' "$output" | tail -c 10000 | report --data-binary @- "$heartbeat_url/$rc"
fi
exit "$rc"

Schedule it with 0 3 * * * /opt/backup-betterstack.sh. With --data-binary @-, curl reads the POST body from standard input and keeps its newlines, and output that happens to start with @ isn't taken for a file name, as it would be with -d "$output" (curl manpage). The backup's output is printed again so cron's mail or your log collector still gets it.

A Period Is Not a Cron Schedule

Because the heartbeat expects one request per period, it fits jobs that run at a fixed interval. Schedules that aren't a fixed interval need workarounds:

• Weekdays only. 0 3 * * 1-5 has gaps of one day and three days, and one period can't match both. The guide says only that "the monitoring period begins from the first heartbeat received"; it doesn't say whether each later deadline is measured from the last request, so test how a weekday heartbeat behaves over a weekend before relying on it. Cron monitoring vs uptime monitoring works through what a fixed interval costs on a weekday job. Per-weekday maintenance windows exist, but the docs don't say what happens to a heartbeat that falls due inside one once the window ends, so test that too.
• Several fixed times a day, such as 06:00 and 18:00, are a fixed interval only when they're evenly spaced; 0 6,20 * * * has gaps of 14 and 10 hours, and one period can't match both.
• Monthly jobs run on calendar dates, and months aren't a fixed number of seconds.

For daylight saving time, Better Stack is ahead. Set server_timezone and the period is evaluated "against wall-clock time, keeping daily and cron-style schedules aligned across daylight saving time changes," for periods of an hour or more (resource_heartbeat.go). CronRadar evaluates every schedule in UTC. A backup at 03:00 Europe/Berlin runs at 01:00 UTC in summer and 02:00 UTC in winter, so CronRadar's schedule docs say to use the earlier time, 0 1 * * *, with a grace of at least an hour plus the run time (schedule syntax). In summer, that extra hour delays every missed-run alert. Cron and daylight saving time covers the general problem.

On grace: Better Stack's 20% suggestion is 17,280 seconds, close to five hours, for a daily job. The request goes out when the job finishes, so the grace has to cover the start delay plus how much the run time varies; anything beyond that only delays the alert. Choosing a grace period shows how to size it from measured runs.

Better Stack Heartbeat Pricing

From the pricing page, checked October 30, 2026:

• Free for personal projects: $0 a month, listing "10 monitors & heartbeats, 1 status page" and "Slack & e-mail alerts."
• Heartbeats: "10 heartbeats included," then each additional 10 heartbeats cost $20 a month, or $17 a month billed annually.
• Responder license: $34 per license per month, or $29 billed annually, which the page describes as "Access to Incidents, including on-call, monitoring and status pages, with unlimited phone call and SMS alerts." The paid side of the page "starts at just $34" and "includes a single responder."

Better Stack's roles page says Admin, Team lead, and Responder each consume a responder license, and the free Member role can't access monitors or heartbeats (managing roles). With the default roles, everyone who needs to see or edit heartbeats uses a responder license.

The pricing page doesn't total a heartbeat-only bill, so the figures below add list prices on monthly billing, assuming one responder license is the minimum paid setup. Confirm the complete quote with Better Stack. CronRadar's columns assume every job is in one schedule class, with unlimited collaborators:

The license buys more than heartbeats: the same seat covers on-call, monitoring, and status pages. Per job, Better Stack's block rate is $2 a heartbeat monthly or $1.70 annually, so for jobs that run more often than every 5 minutes, annual billing comes in below CronRadar's $2 Fast price once the responder licenses are already paid for.

CronRadar's columns use its list prices: Free covers up to 10 active monitors, and on Grow the first 10 stay free and each further monitor costs $2 Fast (gap under 5 minutes), $1 Frequent (5 minutes to under an hour), or $0.50 Standard (hourly or less often) a month, billed in arrears on the month's peak (pricing).

How CronRadar Monitors the Same Job

CronRadar is a hosted monitor for scheduled jobs only. Four things differ from a Better Stack heartbeat (concepts); Dead Man's Snitch vs CronRadar covers in more detail how CronRadar decides a run is late, stuck, or never ran:

• A schedule instead of a period. A monitor holds a standard five-field cron expression evaluated in UTC, plus a gracePeriod in seconds, minimum 60 and default 90. Every check-in moves the expected time to the schedule's next occurrence, so 0 3 * * 1-5 expects nothing on weekends.
• Start, duration, and stuck runs. Besides a plain heartbeat, a job can send start, then complete or fail, paired by a run_id. start and complete record the run's duration, and fail opens an incident immediately with an optional message of up to 1,000 characters. A run that sent start and hangs goes critical as stuck only when the next expected run plus grace passes, about a day later for a daily job, which is later than a success-only heartbeat goes missing; a timeout inside the job turns a hang into a prompt fail (cron job timeouts).
• Outcome checks instead of output. A complete sent by POST can carry up to five numeric or boolean values. Once expectations such as dump_bytes >= 1 are configured in the job's settings, a missing or violated value marks the run as an outcome failure (outcomefailed) and opens an incident. That's the run that exits 0 and does nothing, which a heartbeat records as a success.
• An alert for a job that never ran. A monitor created in the dashboard, by Hangfire discovery, or by Quartz.NET discovery for a job on a repeating simple trigger, is pending until its first expected run plus grace passes, then turns critical and sends a never-executed alert. A monitor created by its own first check-in can't flag a job that never runs, the same gap a Better Stack heartbeat has.

The credential is handled differently too. With Basic auth, as used here, a CronRadar check-in URL holds only the job's monitor key, and the application's API key goes in the Authorization header as the username with an empty password (HTTP API). That key can report for every job in its application, so it needs the same care as a heartbeat URL, but it stays out of URLs, proxy logs, and shell history.

The Dead Man's Snitch guide has a complete CronRadar wrapper for this same 03:00 backup: it reads the API key from a file only the job's account can read, sends start, then complete or fail, gives up on each request after five seconds, ignores errors, and exits with the backup's own code. To also check that the dump isn't empty, drop its Dead Man's Snitch line and replace its report complete line with a complete sent by POST that carries the dump's size:

  # In the wrapper's success branch, in place of "report complete":
  dump_bytes=$(wc -c 2>/dev/null < /var/backups/db-latest.dump || echo 0)
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    --request POST --user "$CRONRADAR_API_KEY:" \
    --header "Content-Type: application/json" \
    --data "{\"outcomes\":{\"dump_bytes\":$dump_bytes}}" \
    "$url/complete?run_id=$run_id" || true

The dump_bytes value is stored only after you configure an expectation for that key; unconfigured keys are accepted and dropped (HTTP API).

For .NET, the CronRadar 1.0.13 package wraps a job with WrapAsync but can't send outcome values; that needs the pending 1.0.14 release. CronRadar.Hangfire 0.1.0 and CronRadar.Quartz 0.1.0 discover recurring jobs, though Quartz 0.1.0 monitors only jobs on repeating simple triggers; Hangfire monitoring and Quartz.NET monitoring cover them, including the published Hangfire 0.1.0's retry caveat. The Node.js, Python, Celery, PHP, and Laravel SDKs aren't installable, so those jobs report over HTTP as above, and HTTP check-ins don't discover jobs automatically.

Better Stack and CronRadar Side by Side

Better Stack facts checked October 30, 2026, from the pages linked above.

The Better Stack notification row combines the API's alert fields, the escalation policies page, and the heartbeat section of the pricing page.

When Better Stack Fits Better

• Your incidents already run through Better Stack. A missed backup pages the same on-call schedule, with phone calls, SMS, critical push, and multi-step escalation, none of which CronRadar has.
• Jobs run on a local clock that observes daylight saving time. server_timezone keeps a daily heartbeat aligned; CronRadar needs a UTC schedule and an extra hour of grace.
• You want the failing job's output on the incident. CronRadar's fail message is capped at 1,000 characters, and it deliberately doesn't collect logs.
• Alerts must reach Microsoft Teams or Zapier, which aren't among CronRadar's five channels.
• You manage monitoring in Terraform, with Better Stack's own provider and its heartbeat resource.
• Many jobs run more often than every 5 minutes, you bill annually, and you already pay for responder licenses, so the $1.70 per-heartbeat block rate undercuts CronRadar's $2 Fast rate.

When a Dedicated Cron Monitor Fits Better

• The schedule isn't a fixed interval: weekdays only, uneven times like 0 6,20 * * *, or the 1st of the month.
• You want more than "it ran": run duration, stuck runs, and outcome checks on what the run produced.
• A job that never runs should alert. Create the monitor in the dashboard, or let Hangfire discovery create it, and it alerts if the first run never arrives.
• Several people need to see job health without a license each.
• Most jobs run hourly or less often, at $0.50 a month each beyond the free 10.
• Your jobs are Hangfire recurring jobs, or Quartz.NET 3.x jobs on repeating simple triggers, that you want discovered instead of wired one at a time.

To move a heartbeat over, take the schedule from the crontab or scheduler rather than from the period, write it in UTC, and run both monitors for one normal schedule window. Confirm a real run reached CronRadar and a test alert reached its recipient before you delete the heartbeat (migration guide). For more options, see cron monitoring tools compared.

Frequently Asked Questions

Do Better Stack heartbeats support cron expressions?

No. A heartbeat takes a period and a grace, both in seconds, and the create-heartbeat API has no schedule field. For periods of an hour or more, server_timezone keeps the period aligned with wall-clock time across daylight saving changes, but a weekday-only or monthly schedule still has to be approximated with a period.

How do I report a failed job to a Better Stack heartbeat?

Request the heartbeat URL with /fail appended, or append the job's exit code and send its output as the request body, which Better Stack says helps diagnose the failure. Send the plain URL only after a successful run, and keep the wrapper's own exit code equal to the job's.

Is the Better Stack heartbeat URL a secret?

Yes. The URL carries a token, and Better Stack's guide calls it a secret URL; the documented requests use no other credential. Anyone with it can report the job as healthy or failed, so keep it in a file only the job's account can read or in a secret store, not in a crontab or repository.

How much do Better Stack heartbeats cost?

As of October 30, 2026, the free personal option lists "10 monitors & heartbeats." On paid plans, 10 heartbeats are included and each additional 10 cost $20 a month, or $17 billed annually. Each Admin, Team lead, or Responder needs a responder license at $34 a month, or $29 billed annually.

What happens if a Better Stack heartbeat never gets its first request?

It stays Pending. Better Stack starts the monitoring period at the first heartbeat, so by its guide's description a job that was never deployed doesn't produce an incident. Send one request when you install the job, and check that the heartbeat has left Pending.

This guide covers Celery 5.6.3, the current release on PyPI (checked October 30, 2026); source links point to the v5.6.3 tag. Which failures deserve a retry, and how other schedulers retry, is in how to retry failed cron jobs. Flower, Prometheus, and worker health are in Celery task monitoring.

How self.retry() Works

# billing/tasks.py
from celery import shared_task

from billing.ledger import LedgerUnavailable, push_ledger_batch


@shared_task(bind=True, max_retries=5, default_retry_delay=120)
def push_ledger(self, batch_id):
    try:
        push_ledger_batch(batch_id)
    except LedgerUnavailable as exc:
        # Overrides default_retry_delay for this attempt only.
        raise self.retry(exc=exc, countdown=60)

retry() publishes a new message with the same task ID to the same queue, then raises Retry, which the worker treats as a state change rather than an error (retrying). The raise in front is for readability, since retry() raises either way. Decorator options become attributes of the task class (base.py), so max_retries=5 above is the same as setting it on a Task subclass.

The defaults live on Task (task.py) and in the autoretry wrapper (autoretry.py):

When Celery Gives Up

self.request.retries is 0 on the first run and goes up by one on each retry (request attributes). retry() gives up when request.retries + 1 exceeds max_retries (task.py), so the default allows 4 runs, and max_retries=5 allows 6. What it raises then depends on exc:

• With exc, it re-raises that exception, so the result backend, logs, and task_failure see LedgerUnavailable, not a Celery wrapper.
• Without exc, it raises MaxRetriesExceededError, whose message is Can't retry <task>[<id>] args:<args> kwargs:<kwargs>. That puts the task's arguments into every place the exception goes, so pass exc.

Three more rules from the same method:

• retry(max_retries=...) applies to that call only. It doesn't carry over to later attempts, and passing None means "use the default", so the only way to retry forever is max_retries=None on the task itself.
• Called as a plain function, retry() raises at once. It raises the exc you passed, or Retry if you passed none, instead of scheduling anything (task.py). Under apply() or task_always_eager, the retry runs immediately in the same process (task.py).
• If the retry can't be published, the retry is lost without a failure. When publishing the new message fails, for example because the broker is unreachable, retry() raises Reject(requeue=False) (task.py). The worker logs a warning, doesn't requeue the current message (request.py), and fires neither task_retry nor task_failure.

autoretry_for and Exponential Backoff

autoretry_for wraps the task's run method. When the method raises a listed exception, the wrapper calls task.retry(exc=exc, **retry_kwargs) for you; Retry, Ignore, and anything in dont_autoretry_for pass through untouched (autoretry.py). An exception that isn't listed fails on the first attempt.

# billing/tasks.py
import os

import requests
from celery import shared_task
from requests.exceptions import ConnectionError as RequestsConnectionError
from requests.exceptions import Timeout


@shared_task(
    autoretry_for=(RequestsConnectionError, Timeout),
    max_retries=5,
    retry_backoff=60,       # Delay ceilings of 60, 120, 240, 480, then 600 seconds
    retry_backoff_max=600,  # The default, shown for clarity
)
def sync_supplier_prices():
    response = requests.post(os.environ["SUPPLIER_SYNC_URL"], timeout=30)
    # A 4xx or 5xx raises HTTPError, which isn't listed: it fails on the first attempt.
    response.raise_for_status()
    return response.status_code

HTTPError, ConnectionError, and Timeout are separate subclasses of RequestException in requests 2.34.2 (exceptions.py), and raise_for_status() raises HTTPError for any 4xx or 5xx status (models.py). Listing RequestException would retry all three, 4xx responses included. To retry a family except some members, list both: autoretry_for=(OSError,) with dont_autoretry_for=(FileNotFoundError,) retries every OSError except a missing file, which Python defines as an OSError subclass (exception hierarchy).

What the Backoff Computes

With retry_backoff on, the wrapper sets the countdown from get_exponential_backoff_interval:

ceiling(n) = min(retry_backoff_max, factor * 2^n)   where n = request.retries (0 on the first failure)
delay(n)   = random integer from 0 to ceiling(n)    if retry_jitter (the default)
           = ceiling(n)                             otherwise

retry_backoff=True makes the factor 1, and a number is used as the factor in seconds, rounded down, with a minimum of 1. Jitter doesn't add noise around the ceiling: it picks a whole number of seconds anywhere from zero up to it, so the average wait is about half of it (retry_jitter).

Two rows deserve a second look. retry_backoff=True at the default max_retries finishes all its retries within seven seconds, too soon for most outages to clear, so pass a factor in seconds instead. And the first row disagrees with the documentation: the tasks guide says that with retry_backoff off "autoretries will not be delayed", but the 5.6.3 wrapper then passes no countdown, and retry() falls back to default_retry_delay, so automatic retries wait three minutes each. Set retry_kwargs={"countdown": 10} for a different fixed delay.

Every delay is a minimum. The retry message carries an ETA, the earliest time it may run, and Celery only guarantees it runs "at some time after the specified date and time" (ETA and countdown), when a worker is free.

acks_late and Worker Loss Are a Different Path

retry() only handles exceptions the task raises. Celery's FAQ is blunt about the other case: retries are "for expected errors that is catch-able with the try block", and "if the task raises an exception it's still acknowledged!", while acks_late is for running the task again "if the worker (for some reason) crashes mid-execution" (retry or acks_late). The three acknowledgement settings and their defaults are in Celery task monitoring; this is how they interact with retries, from the worker's on_failure:

The lost-task row is from the workers guide; under acks_late the message hasn't been acknowledged yet, so it's redelivered to another worker. The last column is the only automatic rerun after a pool process dies, and it isn't counted as a retry: the broker delivers the same message again, and nothing in that path changes request.retries, so max_retries doesn't limit it. A task that reliably kills its own process gets requeued every time, the message loop the configuration reference warns about.

Long retry delays interact with redelivery too. The Redis caveats warn that "ETA/countdown/retry tasks where the time to execute exceeds the visibility timeout" are "executed again, and again in a loop". The visibility timeout is one hour by default on Redis and 30 minutes on SQS, so keep each retry delay well under it; retry_backoff_max at its default of 600 seconds does.

Make Each Attempt Safe to Run Again

A retry and a redelivery both run the task from its first line; idempotent cron jobs covers keying each side effect so a second run doesn't repeat it. The task ID stays the same for every retry of one run, because retry() copies it into the new message, and a redelivery is the same message. That makes self.request.id a usable idempotency key for side effects within one run, such as the key on a payment API call.

It doesn't protect against two separate sends of the same work, such as two beats each sending the 06:00 run: those are two task IDs. For that, key on the period the run covers, as idempotent cron jobs shows with a runs table. Celery's own worker_deduplicate_successful_tasks (default off) covers one narrow case: it skips a redelivered late-acknowledged message whose task ID is already SUCCESS in a persistent result backend. A run that died halfway isn't SUCCESS, so it runs again in full.

Retries for Beat-Scheduled Tasks

Each time an entry is due, beat calls apply_async for it (beat.py) without looking at earlier runs. Every occurrence is a new task with its own ID and its own retry budget, and the 03:00 run of an hourly task is sent on time even if the 02:00 run is still waiting for its fourth attempt. Three consequences:

• A long chain overlaps the next run. With five retries backing off to 600 seconds, a */15 task can have one occurrence's retry running beside, or after, the next occurrence. If the job writes "latest" values, an old retry that finishes last overwrites newer data. Keep the whole chain, retry waits plus run times, shorter than the interval, or prevent overlap with a lock as in preventing overlapping cron jobs.
• A retry inherits the entry's expires. A beat entry can set "options": {"expires": ...} so a backlog doesn't run stale copies. The retry message keeps the original expiry time, which by then is an absolute timestamp (amqp.py), and a worker marks an expired task REVOKED instead of running it (expiration), checking again when the task is about to execute (request.py). A retry that comes due after the expiry never runs, and the chain ends in task_revoked, not task_failure.
• A retry runs late, so "now" is the wrong clock. A nightly job that exports "yesterday" from datetime.now() exports the wrong day if a retry runs after midnight. Fix the period on the first attempt and pass it on, since retry() accepts replacement args and kwargs for the next message (task.py):

# reports/tasks.py
from datetime import datetime, timedelta, timezone

from celery import shared_task

from reports.export import ExportTargetUnavailable, upload_daily_export


@shared_task(bind=True, max_retries=4, default_retry_delay=300)
def export_daily_orders(self, day=None):
    # The first attempt picks the day; every retry receives it as an argument.
    if day is None:
        day = (datetime.now(timezone.utc).date() - timedelta(days=1)).isoformat()
    try:
        upload_daily_export(day)
    except ExportTargetUnavailable as exc:
        raise self.retry(exc=exc, kwargs={"day": day})

kwargs replaces the original keyword arguments rather than merging with them (task.py), so pass all of them. A first attempt that itself starts late, after a backlog, still computes from its own start time; idempotent cron jobs covers naming the period by the work instead of the clock.

Which Hooks Fire on a Retry and Which on the Final Failure

From the tracer (trace.py) and the worker's request handling (request.py):

So task_failure is the final-failure hook: it fires once per run when Celery stops retrying, never for a retry, and it's the only signal or task method that also covers a dead pool process. A Task.on_failure method on a base class misses that case, because it runs in the process that died; Celery's docs point to the worker-side Request.on_failure, which runs in the main process, as a way to detect failures that Task.on_failure doesn't (custom requests). after_return is skipped for RETRY (handlers), so it runs only at the end of a run, though not for a dead pool process.

For per-attempt visibility, use task_retry or task_postrun. task_retry also fires, without reason or einfo, when a running task is cancelled and retried, so a handler must not assume those arguments exist (task_retry).

Report Only the Final Failure to CronRadar

Celery's hooks run only while workers run and beat sends. A schedule-based check from outside covers the rest: no start by the expected time means the run never happened, whichever part failed. CronRadar's Celery SDK is unavailable (checked September 20, 2026; the Celery integration docs carry the current notice), so report with HTTP check-ins. HTTP check-ins don't discover beat schedules: each task needs its own monitor key and its real schedule.

The signal reporter in Celery task monitoring already reports a start for every attempt, nothing for a retry, and a fail only when Celery gives up. This version changes three things for retries:

• The fail handler takes task_id from the task_failure signal. When a pool process dies, the worker's main process sends task_failure (request.py), and that process never pushed this run's request, so sender.request is an empty default context (task.py) and sender.request.id can't be the run_id.
• A task_revoked handler reports a retry that expired, which ends the chain without task_failure.
• Each mapping carries a grace period next to the schedule.

The request code is the standard-library helper from Celery beat not running, with an attempt parameter added: HTTP Basic auth with the key from CRONRADAR_API_KEY, and errors logged instead of raised.

# proj/monitoring.py
import base64
import logging
import os
import urllib.parse
import urllib.request

from celery.signals import task_failure, task_prerun, task_revoked, task_success

log = logging.getLogger(__name__)

# Celery task name -> (monitor key, the beat entry's schedule as five-field cron in UTC,
# grace period in seconds). Schedule and grace apply when a check-in creates the monitor.
MONITORED_TASKS = {
    "reports.tasks.export_daily_orders": ("export-daily-orders", "30 2 * * *", 900),
    "billing.tasks.sync_supplier_prices": ("sync-supplier-prices", "*/15 * * * *", 300),
}


def check_in(task_name, event, *, run_id, attempt=None, message=None):
    """Report one lifecycle event to CronRadar. Never raises into Celery."""
    monitor = MONITORED_TASKS.get(task_name)
    if monitor is None:
        return
    key, schedule, grace_period = monitor
    params = {
        "schedule": schedule,
        "gracePeriod": grace_period,
        "run_id": run_id,
        "attempt": attempt,
        "message": message,
    }
    query = urllib.parse.urlencode(
        {name: value for name, value in params.items() if value is not None},
        quote_via=urllib.parse.quote,
    )
    url = f"https://cron.life/api/v1/ping/{urllib.parse.quote(key, safe='')}/{event}?{query}"
    try:
        token = base64.b64encode(f"{os.environ['CRONRADAR_API_KEY']}:".encode()).decode()
        request = urllib.request.Request(url, data=b"", method="POST")
        # Unlike add_header(), this header is not copied to a redirect.
        request.add_unredirected_header("Authorization", f"Basic {token}")
        with urllib.request.urlopen(request, timeout=5):
            pass
    except Exception as error:
        # A monitoring problem must never fail the task or change its result.
        log.warning("CronRadar %s for %s not recorded (%s)", event, key, type(error).__name__)


@task_prerun.connect
def on_attempt_start(sender=None, task_id=None, task=None, **kwargs):
    # Every attempt shares the task ID; request.retries is 0 on the first.
    check_in(sender.name, "start", run_id=task_id, attempt=task.request.retries)


@task_success.connect
def on_success(sender=None, **kwargs):
    check_in(sender.name, "complete", run_id=sender.request.id, attempt=sender.request.retries)


@task_failure.connect
def on_final_failure(sender=None, task_id=None, exception=None, **kwargs):
    # Never sent for a retry. For a dead pool process it comes from the worker's
    # main process, where sender.request isn't this run, so use task_id.
    # The exception type only: never arguments, payloads, or log output.
    check_in(sender.name, "fail", run_id=task_id, message=type(exception).__name__)


@task_revoked.connect
def on_revoked(sender=None, request=None, expired=False, **kwargs):
    # A retry that outlived the entry's expires ends here, not in task_failure.
    if expired:
        check_in(sender.name, "fail", run_id=request.id, message="Expired")

Load it with app.conf.imports = ["proj.monitoring"], which imports the module when the worker starts. With the prefork pool, the task_failure call for a dead pool process and the task_revoked call run in the worker's main process (custom requests, task_revoked), so a slow check-in there blocks the main process rather than one pool process. timeout=5 limits each blocking operation, such as the connection attempt, not the check-in as a whole (urlopen).

What CronRadar records:

• Each attempt is part of one run. The task ID is the run_id and request.retries is the zero-based attempt (HTTP API reference). CronRadar groups the events that share a run_id into one run and counts its attempts from the distinct attempt values on its starts. It never retries your work itself.
• A retry opens no incident. The failed attempt sends no fail, and the next attempt's start updates the same run.
• The final failure alerts immediately. fail marks the monitor critical with the result failed and opens an incident, alerting through email, Slack, webhook, Discord, or PagerDuty. The alert arrives when the chain ends: for export_daily_orders, at least 20 minutes after the first error (four 300-second waits) plus run times. A later successful run records a recovery.
• Grace covers the first attempt only. Every check-in, each attempt's start included, moves the next expected time to the schedule's next occurrence, so the grace period has to cover how late the first attempt can start, not the retry chain. How a missed run moves from warning to critical is in Celery beat not running.
• A run that ends without a hook stays open. A lost retry message or a killed worker leaves a start with no result, flagged as stuck if no check-in arrives by the next expected time plus grace. If the workers are otherwise fine, the next occurrence's start resets that window, and the lost run stays in the run history labeled running, with no result.
• A chain longer than the interval can alert late. If an old run's final fail arrives after a newer run succeeded, it still opens an incident, for the older run. Short chains avoid that.

Each mapping's schedule is its beat entry written as five-field cron in UTC (schedule syntax); Celery beat not running has a table translating crontab() entries, including ones in other time zones.

Frequently Asked Questions

How many times does Celery retry a task by default?

Zero, unless the task calls self.retry() or lists exceptions in autoretry_for. When it does, max_retries defaults to 3, so a task that keeps failing runs 4 times. max_retries=None retries forever.

What is the default delay between Celery retries?

180 seconds, from default_retry_delay, for both self.retry() without a countdown and autoretry_for without retry_backoff. With retry_backoff=True, the ceilings are 1, 2, and 4 seconds, and the default jitter picks a random delay from zero up to each one.

When does Celery raise MaxRetriesExceededError?

When the retry limit is reached and retry() was called without exc. With exc, Celery re-raises that exception instead, which is what autoretry_for always does. The MaxRetriesExceededError message includes the task's arguments, so pass exc to keep them out of logs and alerts.

Does task_failure fire on every retry?

No. A retry fires task_retry and on_retry. task_failure fires once, when Celery stops retrying or the exception isn't one it retries, and also when the pool process running the task dies and the message isn't requeued. It doesn't fire for a retry that expired, which sends task_revoked.

Does acks_late retry a task that raised an exception?

No. With acks_late, a task that raises is still acknowledged by default, and only retry() or autoretry_for runs it again. acks_late matters when the worker dies mid-task: with task_reject_on_worker_lost as well, a dead pool process puts the message back in the queue, without counting a retry.

Below, each message is traced to the source line that prints it, with what triggers it and the fix. This guide covers cronie 1.7.2, the current release on GitHub; Debian's cron 3.0pl1-197, the version in Debian 13 (tracker.debian.org); and BusyBox 1.37.0, the version in Alpine 3.24 (APKBUILD) (checked October 30, 2026). Debian testing's cron 3.0pl1-212 prints the same messages plus a pathname too long check on the file argument (patch), and BusyBox 1.38.0's crond.c prints the same messages as 1.37.0's. Ubuntu 24.04's cron 3.0pl1-184ubuntu2 prints all of Debian's except unsafe mail (Launchpad). RHEL 9's cronie 1.5.7 carries Red Hat backports of the step-size warning, the -n job option, and the 10,000-entry limit (CentOS Stream 9 cronie.spec), so it prints the same messages as cronie 1.7.2. Editing crontabs and checking one without installing it are covered in the crontab guide; to find out which cron you run, see cron implementations.

Which Cron Printed It

Sources: cronie entry.c, crontab.c, and user.c; Debian entry.c, crontab.c, and the patches cited below; BusyBox crond.c.

How crontab Reports a Bad Line

cronie and Debian check the file when you save from crontab -e, run crontab file, or pipe into crontab -. On the first line that fails, both print the file name, a line number, and the reason with the same format string, "%s":%d: %s (cronie crontab.c, Debian crontab.c), then the summary line:

"/tmp/crontab.Xq3fLa":4: bad minute
Invalid crontab file, can't install.

• The file name is crontab's temporary copy when you used crontab -e (by default /tmp/crontab.XXXXXX on cronie and /tmp/crontab.XXXXXX/crontab on Debian), the path you passed, or - for standard input (cronie, L366-L369; Debian).
• Only the first error is reported. Both stop checking at the first bad line (cronie, Debian). Fix it and check again to find the next one.
• Debian's line number is usually one too low. crontab prints its line count minus one (crontab.c), which is right only once the bad line's newline has been read. Most errors, such as an out-of-range value, a bad name, or a * where the command should start, are found earlier in the line and printed before crontab reads its newline (entry.c), so they're reported against the line above. Bug #571176, still open, shows both cases: PENG AM on line 2 reported as line 1, and a lone BLA on line 4 reported correctly. Check the line after the one named.
• Nothing is installed. crontab file exits with status 1 (cronie, Debian), and crontab -e asks whether to retry, covered below.

bad minute, bad hour, bad day-of-month, bad month, bad day-of-week

These five name the field crontab was parsing when it gave up (cronie entry.c). Both implementations accept the same values in each field (cronie macros.h, Debian cron.h); cron expression syntax lists them and the operators. What triggers the messages in practice:

• A value out of range, such as 60 for a minute, 24 for an hour, 0 or 32 for a day of month, 13 for a month, or 8 for a day of week.
• A full name. Names are three letters in any case, so Jan and mon work and January and Monday don't (cronie entry.c, Debian cron.h).
• Quartz or Spring syntax. ?, L, W, 5L, and MON#1 aren't cron syntax; cron last day of month shows how to get the effect of L. Debian reads every letter and digit into the value, so L, W, and 5L fail there too (entry.c). After a valid value, though, it skips any other characters up to the next blank (L344), so 0 9 * * MON#1 installs there as every Monday, while cronie rejects it.
• A seconds field. Spring and Quartz expressions begin with seconds, so every value lands one field early: 0 30 2 * * *, meant as 02:30:00, puts 30 in the hour field and fails with bad hour.
• A step without a range. 5/15 is bad minute in both (cronie entry.c, Debian patch); write 5-59/15. BusyBox accepts 5/15 without a message and runs only at minute 5 (crond.c).
• A step of zero, as in */0 (cronie, Debian patch).
• A line that isn't a valid variable. Any line that isn't blank, a comment, or NAME=value is parsed as a job, so its first word is read as the minute field (cronie env.c, Debian patch). export PATH=/usr/local/bin:/usr/bin:/bin, source ~/.profile, and MAILTO ops@example.com without its = all fail as bad minute. Write PATH=/usr/local/bin:/usr/bin:/bin; cron environment variables covers what a variable line can and can't do.

The Step-Size Warning Is Not an Error

Warning: Step size 90 higher than possible maximum of 59

cronie and Debian print this for a step larger than the span of the range it steps through, which for * is the whole field, then install the line anyway (cronie entry.c, Debian patch). */90 * * * * then runs at minute 0 of every hour, because the next step lands past 59. A 90-minute interval takes two lines:

0 0-21/3 * * * /opt/app/sync.sh
30 1-22/3 * * * /opt/app/sync.sh

The first runs at 00:00, 03:00, and so on through 21:00; the second at 01:30, 04:30, and so on through 22:30.

bad command

crontab doesn't check that the command exists. cronie prints bad command when nothing follows the time fields, or when the command would start with * (entry.c); Debian's checks only for the * (Better-timeskip-handling.patch). cronie's source says only that the * check catches "a common typo". Among the lines it rejects is a six-field expression whose sixth field is *, like this Spring one:

# "Every 5 minutes" in Spring's six-field syntax: rejected with bad command
0 */5 * * * * /opt/app/poll.sh

# The five-field cron equivalent
*/5 * * * * /opt/app/poll.sh

Only a * is caught. Any other sixth field becomes the start of the command, so the Quartz expression 0 0 2 * * ? /opt/app/report.sh installs without an error and runs the command ? /opt/app/report.sh at 00:00 on the 2nd of every month. Cron's smallest interval is a minute; cron every 30 seconds covers the workarounds.

Other Messages That Refuse a Crontab

premature EOF and the Other Missing-Newline Messages

A crontab whose last line has no newline is refused by both crontab commands; the crontab guide explains why and how to test a file for it. The message depends on which program reads the file:

Sources: cronie crontab.c and user.c; Debian crontab-detect-missing-eol.patch and Abort-processing-of-crontabs-with-errors.patch.

A comment as the last line triggers none of these, because both parsers read a comment through to the end of the file before looking for another entry (cronie misc.c, Debian env.c). The crontab guide's install script adds the newline only when it's missing.

Do You Want to Retry the Same Edit?

cronie and Debian ask this after crontab -e saves a file that fails the check, missing newline included; the crontab guide covers what y and n do, and that BusyBox never asks. cronie's prompt ends in (Y/N) and Debian's in (y/n), both take either case, and any other answer prints Enter Y or N and asks again (cronie crontab.c, Debian crontab.c, Improve-retry-prompt.patch). After n, crontab prints crontab: edits left in /tmp/crontab.Xq3fLa (on Debian, a path ending in /crontab); fix that file and install it with crontab /tmp/crontab.Xq3fLa.

The installed crontab is untouched until a check passes. Two consequences for automation: crontab -e exits with status 0 even after n (cronie, Debian), and neither implementation stops asking when standard input is closed. cronie reprints the prompt when the read fails, and Debian answers its own empty read with Enter Y or N, so a script that drives crontab -e through $EDITOR loops forever on a syntax error. Scripts should install with crontab file, which exits 1 instead; the crontab guide has a script that adds an entry that way without dropping the others.

When the Daemon Finds the Error

Nothing checks /etc/crontab or /etc/cron.d files before the daemon reads them, and the same goes for a user crontab copied into the spool directory instead of installed with crontab. The daemon logs the reason and the file, but not the line:

Sources: cronie user.c and misc.c; Debian Logging-enhancements.patch and Abort-processing-of-crontabs-with-errors.patch. For /etc/crontab, Debian logs while reading /etc/crontab and (*system*); for a user's crontab, while reading crontab for user alice and (alice).

The user field has its own failures, since system crontab lines carry one and user crontabs don't. Debian reads the first word after the time fields as the account and logs bad username when no such account exists, which is what a line missing its user field usually produces (entry.c). cronie loads such a line and, at each scheduled time, logs getpwnam() failed - user unknown instead of running it (entry.c, job.c); with a one-word command, the line is bad command instead.

Find the messages in the journal. Debian's unit is cron (cron.service) and Fedora installs cronie's as crond (cronie.spec):

journalctl -u cron --since today | grep -E 'Error: |ERROR \('   # Debian, Ubuntu
journalctl -u crond --since today | grep -F '(CRON)'            # Fedora, RHEL

To find the line, check a copy of the file with crontab's own parser. This drops the user field from each job line, keeps every other line as it is so line numbers still match, and installs nothing:

# Run as root. Field 6 is the user on a time-field line; field 2 on an @ line.
awk '/^[[:space:]]*(#|$)/ || /^[[:space:]]*[A-Za-z_][A-Za-z0-9_]*[[:space:]]*=/ { print; next }
     /^[[:space:]]*@/ { $2 = ""; print; next }
     { $6 = ""; print }' /etc/cron.d/app > /tmp/app-check.cron

Then check the copy with your implementation's syntax-check option and delete it. The crontab guide's options table lists which versions have -n and -T, and what -n does on cronie instead, so run only your implementation's line:

crontab -n /tmp/app-check.cron && rm /tmp/app-check.cron   # Debian, Ubuntu
crontab -T /tmp/app-check.cron && rm /tmp/app-check.cron   # cronie

The copy can't reveal a missing final newline, because awk ends every line with one, or a missing user field, which Debian's log names as bad username and cronie's as getpwnam() failed - user unknown, or as bad command for a one-word command.

BusyBox: No Check, One Log Message

BusyBox's crontab copies the file into place without parsing it (crontab.c), so it never prints a syntax error. crond parses the file when it next loads it, and for a field it can't read it logs one line (crond.c):

user root: parse error at 60

root is the crontab's file name, which BusyBox uses as its user name (L445), and 60 is the field's text. The line stays loaded, and what the field then matches depends on where parsing stopped:

• An out-of-range number fills the whole field. The fill loop wraps around until a failsafe ends it (crond.c), so 60 in the minute field runs every minute, and 7 in the day-of-week field runs every day, as cron implementations notes.
• An unrecognized character leaves the field empty. L or ? stops parsing before anything is set (crond.c). In the minute, hour, or month field, the line then never runs. In a day field, it never runs only if the other day field is *, because BusyBox runs a line when either day field matches: 0 9 ? * MON still runs every Monday (L336-L360, L912).

Other mistakes produce no message at all:

• A line with fewer than six fields, such as one with no command, is skipped (crond.c).
• An unknown @ keyword is skipped (L542).
• A variable other than MAILTO, SHELL, or PATH is skipped because it has fewer than six fields (L546-L547). One with six or more words, such as MSG=a b c d e f, is read as a job instead and logs parse error.
• A crontab not owned by root is ignored (L440). One named after an account that doesn't exist is logged only at log level 7 or lower, and the default is 8 (L429-L431, L168, L178).

A non-root crontab is also cut off at MAXLINES, 256 by default, with user alice: too many lines (L103-L104, L451-L453). crond logs to syslog unless started with -L FILE, or with -d N, which logs to standard error (crond.c).

Catch the Jobs a Bad Crontab Stops

A refused crontab keeps the old crontab, so a job you meant to add doesn't exist and a job you meant to change keeps its old schedule. On Debian and Ubuntu, one bad line in /etc/crontab, an /etc/cron.d file, or a crontab written outside crontab stops every job in that file, and the only trace is two log lines. Nothing on the host raises an alert.

A check-in monitor notices from outside. With CronRadar, each run reports start, then complete or fail; a fail opens an incident immediately, and a run that hasn't reported by its scheduled time turns its monitor warning, then critical once the grace period runs out. Alerts go by email, Slack, webhook, Discord, or PagerDuty. There's no CronRadar SDK or auto-discovery for crontab, so each job reports with its own HTTP check-in. Cron grace period has a wrapper script that reads the API key from a file only the job's account can read, sends it with HTTP Basic auth, and exits with the job's own status, so the key never appears in the crontab. CronRadar reads every schedule as five fields in UTC, so convert the crontab line's times to UTC, write @ shortcuts out as fields, and use 0, not 7, for Sunday. An entry that restricts both day fields needs two entries, each with its own job key, because CronRadar expects a run only on dates that match both fields, where cron runs on either (schedules).

A monitor created by the job's first check-in doesn't exist until that check-in arrives, so a line that never installed has nothing to go critical. Register each job before its first run with POST /sync in upsert mode instead: a monitor that never receives a check-in then turns critical, with a NeverExecuted alert, once its first expected time plus the grace period has passed.

Frequently Asked Questions

What does "errors in crontab file, can't install" mean?

Debian's or Ubuntu's crontab found a line it couldn't parse, printed it above this message as "FILE":LINE: reason, and kept your current crontab. Fix that line and install again; only the first bad line is reported per check. cronie prints Invalid crontab file, can't install. for the same thing.

What does "bad minute" mean in crontab?

crontab couldn't read the first field of a line. Common causes are a value outside 0-59, a step without a range such as 5/15, and a line that is neither a job nor a valid NAME=value variable, such as export PATH=..., whose first word is read as the minute.

Why does crontab say "premature EOF"?

cronie's crontab prints it when the file's last line has no newline. Add one with echo >> file and install again. Debian's crontab reports the same problem as new crontab file is missing newline before EOF, can't install.

How do I answer "Do you want to retry the same edit?"

Answer y to reopen the editor with your changes and fix the line named above the prompt. Answer n to quit; crontab keeps your edits in the temporary file it names, and the installed crontab is unchanged.

Why doesn't crontab on Alpine report errors?

BusyBox's crontab installs files without parsing them. crond reports a bad field later in its log, as user root: parse error at 60, and silently skips lines with no command, unknown @ keywords, and variable lines of fewer than six words other than MAILTO, SHELL, and PATH.

This guide covers GitLab 19.5.3, the current release on GitLab's release notes (checked October 30, 2026), and cites the GitLab 19.5 documentation for GitLab.com and self-managed instances. The same problems on other CI systems are covered in GitHub Actions scheduled workflows and Jenkins scheduled builds.

Create a Pipeline Schedule

In the project, select Build > Pipeline schedules > New schedule and fill in the fields (scheduled pipelines):

• Interval Pattern: a preconfigured interval or a custom cron pattern.
• Target branch or tag: the ref the pipeline runs for.
• Inputs: values for the spec:inputs in your configuration, "used every time the scheduled pipeline runs", at most 20.
• Variables: CI/CD variables "available only when the scheduled pipeline runs". GitLab recommends inputs instead, and a project setting can refuse schedule variables altogether (see the invalid-configuration section below).

You need the Developer, Maintainer, or Owner role, a verified primary email, merge permission if the target branch is protected, and a .gitlab-ci.yml with valid syntax. Whoever creates the schedule becomes its owner, and "the pipeline runs with your permissions." A project can hold 10 schedules by default (number of pipeline schedules); GitLab.com allows 10 on Free and 50 on paid tiers (GitLab.com settings).

Cron Syntax and Time Zone

The pattern has five fields: minute, hour, day of month, month, and day of week, 0 to 6 for Sunday to Saturday (cron syntax). GitLab parses it with fugit, which also accepts 0 0 * * 1#2 for the second Monday and 0 9 * * sun%2 for every other Sunday, syntax GitLab warns "might not work in all cron testers" (how GitLab parses cron). Cron expression syntax covers the standard fields and how other schedulers' dialects differ.

Each schedule carries its own zone. The pipeline schedules API calls it cron_timezone, a "time zone supported by ActiveSupport::TimeZone, for example: Pacific Time (US & Canada)", with a default of UTC. To create a schedule in UTC with an access token in GITLAB_TOKEN:

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --form "description=Nightly report" \
  --form "ref=main" \
  --form "cron=17 3 * * *" \
  --form "cron_timezone=UTC" \
  --url "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipeline_schedules"

GitLab's documentation doesn't say what a schedule in a zone with daylight saving does in the hour that is skipped in spring or repeated in autumn. Cron and daylight saving time shows how other schedulers differ there; a cron_timezone of UTC avoids the question.

How Often GitLab Actually Starts a Scheduled Pipeline

GitLab's limits page explains the gap. Scheduled pipelines "do not always run exactly when scheduled. An internal process, called the 'pipeline schedule worker', queues all the scheduled pipelines, but does not run continuously." A due pipeline is "only queued the next time the worker runs", and "scheduled pipelines can't run more frequently than the worker" (maximum scheduled pipeline frequency).

The GitLab.com values come from its CI/CD settings. On self-managed, ci_daily_pipeline_schedule_triggers defaults to 0 (db/structure.sql), and GitLab ignores a limit that isn't positive (plan_limits.rb), so only the worker sets the pace. What they do to a schedule:

• The worker adds a wait. A 17 3 * * * schedule is queued at the 03:20 worker run on GitLab.com paid tiers, and at 03:23 on a default self-managed instance. On GitLab.com Free, the 24-a-day limit moves it to 04:00: GitLab keeps the schedule's own time only when a worker run falls on it, and otherwise uses the next full hour (next-run calculation). GitLab's tests expect a 59 14 * * * schedule under that limit to run at 15:00 (spec), while 15 3 * * * runs at 03:15.
• Schedules faster than the limits are slowed. "Schedules that try to run pipelines more frequently than the limit are slowed to a maximum frequency": 1,440 minutes divided by the daily limit (pipelines per schedule). With GitLab.com Free's 24, that's once every 60 minutes, so a */15 * * * * schedule runs at most hourly. On a default self-managed instance, a */5 schedule can't run more often than the worker's 10 minutes.
• Load adds more. The worker processes schedules in batches "with a small delay between each batch to distribute system load. This can cause pipeline schedules to start several minutes to over an hour after their scheduled time, depending on system load."

Then the pipeline's jobs wait for a runner like any others. A pending job is dropped after 1 hour with no matching runners (stuck_pending_no_matching_runners) and after 24 hours with matching ones (stuck_pending_with_matching_runners) (dropped jobs). On instance runners with a compute quota, which GitLab.com enables for Free namespaces at 400 minutes a month (compute minutes), a used-up quota means "instance runners stop processing new jobs", and GitLab notes this "can look like a runner availability problem" (enforcement).

Stagger schedules. GitLab's troubleshooting advice is to replace popular patterns such as 0 * * * * with ones spread across the hour, like 5 * * * *, 15 * * * *, and 25 * * * * (distribute pipeline schedules). Cron jitter covers choosing offsets; on GitLab.com Free, keep them to multiples of 5 minutes so a worker run falls on them.

On self-managed, the limits are yours. Set gitlab_rails['pipeline_schedule_worker_cron'] in gitlab.rb and reconfigure GitLab to change the worker; GitLab's example, 0 */12 * * *, caps every schedule at twice a day. To add a daily limit, set it in the Rails console with Plan.default.actual_limits.update!(ci_daily_pipeline_schedule_triggers: 1440), where 1440 allows one pipeline a minute, and Plan.default.actual_limits lists the current values.

Measure the Delay

The API lists each pipeline a schedule created, with its created_at (pipelines of a schedule). For the daily 17 3 * * * UTC schedule, this prints how many minutes after 03:17 each recent pipeline was created:

curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipeline_schedules/$SCHEDULE_ID/pipelines?sort=desc" \
  | jq '.[].created_at | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601 | (. % 86400 - (3 * 3600 + 17 * 60)) / 60 | floor'

That covers the worker wait and batching. The runner wait comes after it, and the start check-in further down measures both. A day missing from the list is a day the schedule created no pipeline.

Why a Pipeline Schedule Stops Running

Ownership. "Scheduled pipelines execute with the permissions of the user who owns the schedule." If one turns Inactive unexpectedly, "the schedule owner might have been blocked or removed from the project" (troubleshooting). Before each run, GitLab checks that the owner can still create pipelines in the project; if not, it creates no pipeline, emails the project's Owners and Maintainers, and deactivates the schedule (run_pipeline_schedule_worker.rb). The docs say taking ownership reactivates it, but in 19.5.3 the UI and the API only change the owner (take_ownership_service.rb, pipeline_schedules.rb). After Take ownership, edit the schedule, select Activated, and save, or update it with active=true. Take ownership requires the Maintainer or Owner role; the API equivalent is POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership (ownership API). Before someone leaves, they can find every active schedule they own under their avatar > Edit profile > Account > Scheduled pipelines you own, available since GitLab 18.4 (your scheduled pipelines).

A manual run uses your permissions. "When you run a scheduled pipeline manually, it uses your permissions instead of the schedule owner's permissions" (run manually), so its jobs get your access, not the owner's, to things like protected environments and the CI/CD job token. GitLab still checks the owner first: if the owner can no longer create pipelines, a manual run creates no pipeline and deactivates the schedule (play_service.rb, run_pipeline_schedule_worker.rb). The API's play endpoint runs a schedule immediately, and "the next scheduled run of this pipeline is not affected."

To list a project's inactive schedules and who owns them, use the scope filter of the list endpoint:

curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://gitlab.com/api/v4/projects/$PROJECT_ID/pipeline_schedules?scope=inactive" \
  | jq -r '.[] | [.id, .description, .cron, .cron_timezone, .owner.username] | @tsv'

Scheduled job inventory covers collecting schedules across projects.

Rules and Workflow Conditions for Scheduled Pipelines

CI_PIPELINE_SOURCE is schedule in scheduled pipelines (pipeline sources). GitLab's own example puts one job in scheduled pipelines only and another in push pipelines only (run jobs for scheduled pipelines):

nightly-report:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - ./scripts/nightly-report.sh

build:
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
  script:
    - make build

The conditions that decide whether a schedule produces anything:

• workflow:rules come first. "The workflow keyword is evaluated before jobs" (workflow), and "when no rules evaluate to true, the pipeline does not run" (workflow:rules). A workflow that allows only push and merge_request_event blocks every schedule; add - if: $CI_PIPELINE_SOURCE == "schedule".
• No jobs, no pipeline. "A pipeline does not run if no jobs are added to it at the end of the evaluation" (debugging), and "if a pipeline contains only jobs in the .pre or .post stages, it does not run."
• Branch rules match schedules too. A branch pipeline "can be triggered by a change to a branch, an API call, or a scheduled pipeline" (workflow), and CI_COMMIT_BRANCH is "available in branch pipelines, including pipelines for the default branch" (predefined variables), so a job with if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH also runs in schedules on the default branch. GitLab's reuse example puts if: $CI_PIPELINE_SOURCE == "schedule" with when: never first to exclude them.
• changes is always true. "All files are considered to have changed when a scheduled pipeline runs, so jobs might always be added to scheduled pipelines that use changes" (troubleshooting).
• Several schedules, one file. CI_PIPELINE_SCHEDULE_DESCRIPTION, added in 17.8, holds "the description of the pipeline schedule" and is available to rules (predefined variables). Inputs set on each schedule, shown at the end of this guide, don't depend on a description someone may edit.

What Happens When the Configuration Is Invalid

A schedule needs valid syntax when it's created, but a later commit to its target branch can still break the file. Then "the pipeline shows a yaml invalid badge and does not start running" (verify syntax). No job runs, including any job meant to report the failure.

• Validate before merging. The pipeline editor checks syntax automatically, and the CI Lint tool can simulate a pipeline. The simulation "runs as a Git push event on the default branch" (simulate a pipeline), so jobs whose rules require schedule don't appear in it. To check those, select Run next to the schedule, which triggers it "immediately instead of waiting for the next scheduled time", and inspect the pipeline it creates.
• Inputs need defaults. "If any input is missing a default, the pipeline fails when it triggers automatically," for example in merge request and branch pipelines (pipeline inputs). A schedule supplies its own values, but the other pipelines in the project don't.
• Schedule variables can be refused. Variables set on a schedule are pipeline variables, and Minimum role to use pipeline variables can block them. Its no_one_allowed value is the default "for new projects in new namespaces on GitLab.com", and with it, "no pipelines can run with pipeline variables" (restrict pipeline variables). GitLab recommends inputs over pipeline variables and suggests disabling pipeline variables when you use inputs (pipeline variables).

Failed-Pipeline Notifications

GitLab has two ways to email about a failed pipeline:

• Personal notifications. "CI/CD pipeline event notifications are sent to the pipeline creator": a failed pipeline at the Watch level or with Pipeline fails selected under Custom, and a fixed one only with Pipeline is fixed under Custom (pipeline events). GitLab sends nothing to blocked, banned, or deactivated accounts.
• Pipeline status emails. Under Settings > Integrations > Pipeline status emails, a Maintainer or Owner enters a list of recipients and can select Notify only broken pipelines, Notify only when status changes, and which branches to notify for. "Pipeline notifications triggered by blocked users are not delivered" (pipeline status emails).

Both report on pipelines that exist, so a schedule that's inactive, blocked by workflow:rules, or in a project marked for deletion triggers neither. When GitLab deactivates a schedule because the owner can no longer create pipelines, it does email the project's Owners and Maintainers (run_pipeline_schedule_worker.rb, notification_service.rb). That gap is what a dead man's switch covers: the pipeline checks in, and an outside monitor alerts when a check-in doesn't arrive on schedule.

Check In to CronRadar From the Pipeline

CronRadar has no SDK or integration for GitLab and doesn't discover pipeline schedules, so each schedule reports with HTTP check-ins from its own jobs.

1. Store the key. In Settings > CI/CD > Variables, add CRONRADAR_API_KEY with Visibility set to Masked and hidden (mask, hide). A masked value must be a single line with no spaces and at least 8 characters, which a CronRadar key, ck_app_ followed by letters, digits, and underscores, is. GitLab replaces a masked value with [MASKED] in job logs, and a hidden one "cannot be revealed in the UI again." Protect variable limits the key to pipelines on protected branches and tags (protect), and "the default branch for your repository is protected by default" (protected branches), so a schedule targeting it still gets the key. Keep it out of .gitlab-ci.yml: GitLab says tokens "should be stored in the settings in the UI, not in the .gitlab-ci.yml file" (variables in the UI).
2. Create the monitor first. In the CronRadar dashboard, create a monitor with the key nightly-report, the schedule 17 3 * * *, and a 3,600-second grace period. It stays pending, and if the first expected run plus the grace period passes with no check-in, CronRadar sends a never-executed alert. A monitor created by its own first check-in can't flag a schedule whose rules never let it run.
3. Add the check-in jobs, with the schedule's cron_timezone set to UTC:

# .gitlab-ci.yml
stages:
  - report

.cronradar:
  variables:
    PING_URL: https://cron.life/api/v1/ping/nightly-report
    MONITOR_SCHEDULE: '17 3 * * *' # the pipeline schedule's cron, in UTC
    GRACE_SECONDS: '3600'
  before_script:
    - |
      check_in() {
        curl --fail --silent --show-error --max-time 5 --output /dev/null \
          --request POST --get --user "$CRONRADAR_API_KEY:" \
          --data-urlencode "schedule=$MONITOR_SCHEDULE" \
          --data-urlencode "gracePeriod=$GRACE_SECONDS" \
          --data-urlencode "run_id=$CI_PIPELINE_ID" \
          "$@" || true
      }

cronradar-start:
  extends: .cronradar
  stage: .pre
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      allow_failure: true
  script:
    - check_in "$PING_URL/start"

nightly-report:
  stage: report
  timeout: 30 minutes
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - ./scripts/nightly-report.sh

cronradar-complete:
  extends: .cronradar
  stage: .post
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: on_success
      allow_failure: true
  script:
    - check_in "$PING_URL/complete"

cronradar-fail:
  extends: .cronradar
  stage: .post
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: on_failure
      allow_failure: true
  script:
    - check_in --data-urlencode "message=Scheduled pipeline failed: $CI_PIPELINE_URL" "$PING_URL/fail"

• start runs first. .pre "is the first stage in a pipeline" (.pre), so start arrives when a runner takes the pipeline's first job, after the worker wait, any batching delay, and the runner queue.
• One result job runs. when: on_success runs a job "only when no jobs in earlier stages fail", and when: on_failure "only when at least one job in an earlier stage fails" (rules:when). Two .post jobs are needed because each job takes one condition. fail alerts immediately. Jobs with allow_failure: true in earlier stages "are considered successful, even if they failed" (when), so their failures report complete.
• Timeouts report as failures. A job that runs past its timeout fails (timeout); without one, the project timeout applies, 60 minutes by default (job timeout). Set timeout a little above the longest normal run; cron job timeouts covers timeouts on the calls that hang.
• Monitoring can't fail the pipeline. Each request gives up after 5 seconds and || true ignores its errors. With allow_failure: true, a check-in job that fails anyway shows a warning while "the pipeline is successful" (allow_failure), and later stages still run. The jobs use your default image; if it has no curl, || true hides the error and no check-in arrives, so give .cronradar an image: that has curl.
• The helper is shared. before_script and script "execute together in a single shell" (before_script), so each job can call check_in.
• One pipeline, one run ID. CI_PIPELINE_ID "is unique across all projects on the GitLab instance" (predefined variables), and start and the result send the same value.
• Self-registering. schedule and gracePeriod apply only when a check-in creates the monitor, so a deleted monitor comes back on the next run. Change an existing monitor's values in its settings.
• No pipeline is what alerts. An inactive schedule, a pipeline blocked by rules, a yaml invalid pipeline, a pipeline left with only the check-in jobs (which doesn't run), and jobs that never leave pending all send nothing; once the expected time plus the grace period passes, the monitor goes critical as missed. If start arrives and neither result does, it goes critical as stuck once the next scheduled time plus the grace period passes.

Alerts go to email, Slack, a webhook, Discord, or PagerDuty. In a real project, keep each existing job's own rules: the check-in jobs only need to share the pipeline with them.

Choosing the Grace Period

With start as the first job, the grace period covers only the start delay (grace periods explains why). On GitLab that delay has three parts: the worker wait, up to the worker's 5 or 10 minutes, or up to an hour on GitLab.com Free for a minute that isn't a multiple of 5; batching under load, which GitLab puts at "several minutes to over an hour"; and the runner queue.

• Daily or less often: 3,600 seconds. That absorbs a badly delayed run, and hearing about a nightly report an hour late rarely changes anything. Raise it if the created_at measurements above come close.
• Hourly or more often: less than the interval, more than the worker. Every check-in moves the expected time to the schedule's next occurrence, so with a grace longer than the interval, the next run checks in before a missed one is flagged; GitHub Actions scheduled workflows works through that trade-off. For an hourly 17 * * * * schedule on GitLab.com paid tiers or a default self-managed instance, 1,200 seconds flags each missing run, at the cost of an alert whenever a run starts more than 20 minutes late. On GitLab.com Free that schedule runs on the next full hour, 43 minutes late, so every run would alert; 15 * * * * runs at :15 there. A grace shorter than the worker's wait turns ordinary runs into alerts.
• Send the schedule GitLab can keep. On GitLab.com Free, a */15 * * * * schedule runs once an hour, on the hour, so a CronRadar monitor expecting */15 would go critical between every pair of runs. Schedule no more often than your plan's limit and your instance's worker allow, and send that cron. On Free, either use a minute that's a multiple of 5 or send CronRadar the time GitLab runs: 0 4 * * * for 17 3 * * *.

Schedules With a Time Zone, or Several Schedules

CronRadar evaluates every schedule in UTC (schedule syntax). With cron_timezone set to UTC, send the cron unchanged. A schedule in a zone with daylight saving runs at a different UTC time in summer and winter: 0 6 * * * in Berlin is 04:00 UTC in summer and 05:00 UTC in winter, so by CronRadar's time zone rule, which GitHub Actions scheduled workflows works through, send 0 4 * * * with 7,200 seconds of grace instead of 3,600.

CronRadar's syntax has no # or %. For fugit's second Monday, 0 0 * * 1#2, send 0 0 8-14 * 1, which CronRadar reads as a Monday between the 8th and the 14th because it requires a date to match both day fields. Don't schedule GitLab itself with both day fields restricted: GitLab 19.5.3 parses schedules with fugit 1.11.2 (Gemfile.lock), which follows crontab(5) and runs the schedule "when either field matches" (fugit README).

For several schedules in one project, give each its own monitor with pipeline inputs. Add a header to the top of .gitlab-ci.yml, with defaults so push and merge request pipelines still start:

spec:
  inputs:
    monitor_key:
      default: nightly-report
    monitor_schedule:
      default: '17 3 * * *'
---
.cronradar:
  variables:
    PING_URL: https://cron.life/api/v1/ping/$[[ inputs.monitor_key ]]
    MONITOR_SCHEDULE: '$[[ inputs.monitor_schedule ]]'
    GRACE_SECONDS: '3600'

This replaces the variables of .cronradar; its before_script and the jobs stay as above. Then set monitor_key and monitor_schedule in each schedule's Inputs.

Frequently Asked Questions

Why is my GitLab scheduled pipeline not running?

Open Build > Pipeline schedules. A schedule marked Inactive may have an owner who was blocked or removed from the project; a Maintainer or Owner can select Take ownership, then edit the schedule and select Activated, because taking ownership alone leaves it inactive. If the schedule is active, look for a yaml invalid pipeline on its target branch, workflow:rules or job rules that add no jobs when CI_PIPELINE_SOURCE is schedule, and jobs stuck pending without a runner or compute minutes. Schedules also stop when the project or group is marked for deletion.

Why does my GitLab scheduled pipeline start late?

GitLab queues due pipelines only when its pipeline schedule worker runs: every 5 minutes on GitLab.com, and every 10 minutes (3-59/10 * * * *) by default on self-managed instances. On GitLab.com Free, a schedule whose minute isn't a multiple of 5 waits for the next full hour. Under load, batching can add several minutes to over an hour, and the jobs then wait for a runner. Stagger schedules away from the top of the hour, in multiples of 5 minutes on Free, and measure the delay from each scheduled pipeline's created_at.

Can a GitLab pipeline schedule run every minute?

Not on GitLab.com. Its worker runs every 5 minutes, and Free namespaces are limited to 24 pipelines per schedule per day, which slows a schedule to once an hour at most; paid tiers allow 288, one every 5 minutes. On a self-managed instance, an administrator can run the worker every minute with pipeline_schedule_worker_cron. There's no daily limit by default; if one has been set, ci_daily_pipeline_schedule_triggers must be 1440 to allow a pipeline a minute.

What time zone do GitLab pipeline schedules use?

Each schedule has its own cron_timezone, which defaults to UTC when you create the schedule through the API. GitLab's documentation doesn't describe what happens in an hour that daylight saving time skips or repeats, so UTC is the predictable choice, and it matches what CronRadar expects.

How do I run a job only in GitLab scheduled pipelines?

Give the job rules: - if: $CI_PIPELINE_SOURCE == "schedule", and use the same condition with when: never to keep other jobs out of scheduled pipelines. If the file has workflow:rules, one of them must also match schedules, or the scheduled pipeline doesn't run at all.

How do I get alerted when a GitLab schedule doesn't run?

GitLab's pipeline emails cover pipelines that exist, so a pipeline blocked by rules or a schedule someone deactivated sends nothing. When GitLab itself deactivates a schedule because its owner can no longer create pipelines, it emails the project's Owners and Maintainers. Add check-in jobs in the .pre and .post stages that report to an external monitor, which alerts when a check-in doesn't arrive within a grace period of the scheduled time. With CronRadar, create the monitor before the first run so even a schedule that never runs produces a never-executed alert, and a fail check-in alerts at once.

This guide covers Hangfire.Core and Hangfire.AspNetCore 1.8.25, the current release on NuGet (checked October 30, 2026). For reading job state in code instead of through the UI, see Hangfire monitoring.

Why the Dashboard Returns 401 Off Localhost

A new DashboardOptions() sets Authorization to a single LocalRequestsOnlyAuthorizationFilter (DashboardOptions.cs). UseHangfireDashboard() and MapHangfireDashboard() called without options use a DashboardOptions registered in DI if there is one, and that default otherwise (HangfireApplicationBuilderExtensions.cs, HangfireEndpointRouteBuilderExtensions.cs). The dashboard documentation states it directly: "By default Hangfire allows access to Dashboard pages only for local requests."

The filter reads HttpContext.Connection.RemoteIpAddress (AspNetCoreDashboardRequest.cs) and allows the request only when (LocalRequestsOnlyAuthorizationFilter.cs):

• the remote address is 127.0.0.1 or ::1,
• the remote address equals the local address of the connection, or
• the remote address parses as a loopback address, such as ::ffff:127.0.0.1.

An empty remote address is treated as not local. So the dashboard works on your machine and fails as soon as the browser is somewhere else.

401 or 403: what the status code tells you

When any filter returns false, the dashboard middleware sets the status code and writes nothing else (AspNetCoreDashboardMiddleware.cs):

The middleware does not call your authentication scheme's challenge, so a filter refusal never redirects to a login page. If you are signed in and a page load (not a button action) gets 401, Hangfire saw an unauthenticated HttpContext.User. A 401 on delete, requeue, or trigger means IsReadOnlyFunc returned true (CommandDispatcher.cs). Middleware runs in the order it is added (Microsoft middleware order), so call UseAuthentication before UseHangfireDashboard. Hangfire's "Method call order is important" note in the dashboard documentation gives the same rule for OWIN Startup classes.

Replace the Filter With IDashboardAuthorizationFilter

IDashboardAuthorizationFilter has one method, bool Authorize(DashboardContext context), and GetHttpContext() from Hangfire.AspNetCore gives you the ASP.NET Core HttpContext (AspNetCoreDashboardContextExtensions.cs):

using Hangfire.Dashboard;

public sealed class HangfireAdminFilter : IDashboardAuthorizationFilter
{
    public bool Authorize(DashboardContext context)
    {
        var user = context.GetHttpContext().User;

        return user.Identity?.IsAuthenticated == true
            && user.IsInRole("HangfireAdmin");
    }
}

Assigning Authorization replaces the default list, so the local-only filter is gone:

using Hangfire;

app.UseAuthentication();
app.UseAuthorization();

app.UseHangfireDashboard("/hangfire", new DashboardOptions
{
    Authorization = new[] { new HangfireAdminFilter() }
});

When you pass several filters, every one must return true (documentation). The middleware runs all synchronous filters first, then the async ones, and stops at the first refusal.

The async variant

Use IDashboardAsyncAuthorizationFilter, whose single method is Task<bool> AuthorizeAsync(DashboardContext context) (IDashboardAsyncAuthorizationFilter.cs), when the check has to await something, such as a policy evaluation or a lookup. This one evaluates a named ASP.NET Core policy through IAuthorizationService.AuthorizeAsync:

using Hangfire.Dashboard;
using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.DependencyInjection;

public sealed class HangfirePolicyFilter : IDashboardAsyncAuthorizationFilter
{
    public async Task<bool> AuthorizeAsync(DashboardContext context)
    {
        var httpContext = context.GetHttpContext();
        var authorization = httpContext.RequestServices
            .GetRequiredService<IAuthorizationService>();

        var result = await authorization.AuthorizeAsync(httpContext.User, "HangfireViewer");
        return result.Succeeded;
    }
}

app.UseHangfireDashboard("/hangfire", new DashboardOptions
{
    AsyncAuthorization = new[] { new HangfirePolicyFilter() }
});

Setting AsyncAuthorization also clears Authorization, but only while Authorization still holds the built-in default (DashboardOptions.cs). If you set both, both lists run.

Use an ASP.NET Core Authorization Policy

With endpoint routing, Hangfire.AspNetCore has three mapping methods (HangfireEndpointRouteBuilderExtensions.cs). MapHangfireDashboard has two overloads: one without a pattern, which maps /hangfire, and one whose pattern is required. The other two default pattern to "/hangfire".

The policy method is the shortest route to a production setup:

using Hangfire;

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("HangfireViewer", policy => policy
        .RequireAuthenticatedUser()
        .RequireRole("HangfireAdmin", "Operations"));
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapHangfireDashboardWithAuthorizationPolicy("HangfireViewer");

Two consequences follow from the source:

• Filters you pass are discarded. MapHangfireDashboardWithAuthorizationPolicy and MapHangfireDashboardWithNoAuthorizationFilters overwrite Authorization and AsyncAuthorization on the options object you give them. Put every access rule in the policy.
• MapHangfireDashboard(...).RequireAuthorization(...) keeps the local-only filter. Plain MapHangfireDashboard doesn't touch the filters, so a user who passes your policy from a remote browser still gets 401 or 403 from Hangfire. Use the policy method, or set Authorization yourself.

MapHangfireDashboardWithNoAuthorizationFilters with no RequireAuthorization after it leaves the dashboard open to anyone who can reach the URL.

Make the Dashboard Read-Only for Some Users

IsReadOnlyFunc takes a Func<DashboardContext, bool> and defaults to _ => false, so everyone who gets in has full control (DashboardOptions.cs). Hangfire evaluates it once per request (DashboardContext.cs). This gives the HangfireViewer policy access, and buttons only to HangfireAdmin:

using Hangfire;
using Hangfire.Dashboard;

app.MapHangfireDashboardWithAuthorizationPolicy("HangfireViewer", options: new DashboardOptions
{
    IsReadOnlyFunc = context =>
        !context.GetHttpContext().User.IsInRole("HangfireAdmin")
});

The documentation describes the read-only view as one that "prevents users from changing anything, such as deleting or enqueueing jobs." It is enforced on the server too: the command dispatchers behind those buttons return 401 when IsReadOnly is true (CommandDispatcher.cs, BatchCommandDispatcher.cs).

Read-only controls actions, not visibility. A read-only viewer still opens every page, and the dashboard documentation warns that the dashboard "exposes sensitive information about your background jobs, including method names and serialized arguments." Decide who gets in with authorization. DisplayStorageConnectionString also defaults to true; set it to false if viewers shouldn't see which storage the dashboard reads.

Behind a Reverse Proxy or Path Base

A same-host proxy makes every request look local

LocalRequestsOnlyAuthorizationFilter trusts the connection's remote address. When Nginx, Caddy, or another proxy on the same host forwards to Kestrel over 127.0.0.1 and nothing rewrites the address, the remote address is the proxy's loopback address, and the filter allows every visitor. When the proxy runs on another machine or container, the remote address is that proxy's, and the filter refuses everyone: 401 for anonymous visitors, 403 for signed-in users.

ASP.NET Core's Forwarded Headers Middleware can rewrite HttpContext.Connection.RemoteIpAddress from X-Forwarded-For, and by default it accepts those headers only from loopback proxies (Microsoft proxy documentation); a proxy elsewhere has to be added to KnownProxies or KnownNetworks. Either way, an IP check is the wrong control for a production dashboard. Replace the default with a filter or policy that checks the signed-in user.

Links break under a stripped prefix

Every dashboard link is built as PrefixPath + Request.PathBase + relativePath (UrlHelper.cs). If the public URL is https://example.com/ops/hangfire and the proxy strips /ops before forwarding, the app never sees /ops, so the dashboard's CSS, scripts, and links point at /hangfire/... and fail. Two fixes, depending on what the proxy forwards:

• The proxy strips the prefix: set PrefixPath = "/ops". Its source comment describes the result as {domain}/{PrefixPath}/{hangfire}.
• The proxy keeps the prefix: call app.UsePathBase("/ops"), which moves /ops into Request.PathBase. With WebApplication, call UseRouting after UsePathBase so routing sees the rewritten path (Microsoft proxy documentation).

app.MapHangfireDashboardWithAuthorizationPolicy("HangfireViewer", options: new DashboardOptions
{
    // The proxy serves https://example.com/ops/hangfire and strips /ops.
    PrefixPath = "/ops",
    // The Back to site link; null hides it.
    AppPath = "/ops/"
});

AppPath defaults to /. To move the dashboard itself, change the pattern: UseHangfireDashboard("/jobs") or MapHangfireDashboardWithAuthorizationPolicy("HangfireViewer", "/jobs").

What the Dashboard Cannot Do

The dashboard reads storage and renders a page only when someone requests one. Its live counters update by polling /stats from an open page every StatsPollingInterval, 2,000 milliseconds by default, and no DashboardOptions setting sends a notification (DashboardOptions.cs, DashboardRoutes.cs, LayoutPage.cshtml, hangfire.js). Hangfire monitoring covers when to add a schedule-based alert, Hangfire recurring job not running covers runs that never start, Hangfire job stuck in processing covers runs that start and never finish, and dead man's switch explains why the check that a run happened belongs outside the process.

Alert on Missed and Failed Runs With CronRadar

CronRadar is a cron-only monitoring service. It knows each recurring job's schedule and alerts when a run fails or hasn't arrived by the end of its grace period, by email, Slack, webhook, Discord, or PagerDuty. The alert comes from CronRadar, not from the Hangfire host, so it still fires when that host is down.

Store the CronRadar application key as CRONRADAR_API_KEY in your environment or secret store, not in appsettings.json or any committed file. Then install the package in the host that runs the Hangfire server:

dotnet add package CronRadar.Hangfire

using CronRadar.Hangfire;

// After your existing AddHangfire(...) and AddHangfireServer() calls.
// Reads the key from the CRONRADAR_API_KEY environment variable.
builder.Services.AddCronRadarHangfire();

In the published 0.1.0 (NuGet, checked October 30, 2026), that call adds an execution filter that reports each recurring job's start, completion, and failure, and a hosted service that declares every recurring job and its cron expression at startup. Monitoring errors are caught, so they can't fail a job. A recurring job with no start after its expected time goes from warning to critical once the grace period passes. To exclude a job, put [SkipMonitor] on its method.

Two things show up in the dashboard you just secured:

• A cronradar:reconcile recurring job. The package registers it to re-declare the registry every 15 minutes by default (reconcileIntervalMinutes, clamped to 1 through 59). If an admin deletes it from the Recurring Jobs page, it is registered again the next time the host starts. A read-only viewer can't delete it.
• Early failure reports. CronRadar.Hangfire 0.1.0 can report a failure before Hangfire finishes retrying, including cancellations, so a job that later succeeds on retry can still alert. Reporting only after retries are exhausted requires the pending 0.2.1 release.

CronRadar evaluates schedules in UTC; for jobs with a non-UTC RecurringJobOptions.TimeZone, see Hangfire cron expressions and time zones. The Hangfire integration guide has the full setup and the current release notice. Keep the dashboard for retries, requeues, and debugging; CronRadar tells you when to open it.

Frequently Asked Questions

Why does the Hangfire dashboard work locally but return 401 in production?

The default DashboardOptions.Authorization is LocalRequestsOnlyAuthorizationFilter, which allows only loopback addresses or a remote address equal to the local one. A browser on another machine fails it and, unauthenticated, gets 401. Replace the filter or use MapHangfireDashboardWithAuthorizationPolicy.

Why do I get 403 instead of 401?

Hangfire returns 403 when a filter refuses a user who is already authenticated, and 401 when the user isn't. A 403 on a button click can also be a failed anti-forgery check.

Can I use RequireAuthorization with MapHangfireDashboard?

You can, but MapHangfireDashboard keeps the local-only default filter, so remote users are still refused. MapHangfireDashboardWithAuthorizationPolicy removes the filters and applies RequireAuthorization for you.

Does read-only mode hide job arguments?

No. IsReadOnlyFunc blocks deleting, requeuing, and triggering, and the server rejects those commands with 401. Every page stays visible, so restrict who gets in with authorization.

Is it safe to expose the dashboard behind Nginx on the same server?

Not with the default filter. Unless forwarded headers rewrite the remote address, the proxy connects from 127.0.0.1, so LocalRequestsOnlyAuthorizationFilter lets every visitor in. Use a filter or policy that checks the signed-in user.

Can the Hangfire dashboard send alerts?

No. It renders pages on request and has no notification setting. Use an external check, such as CronRadar, to be told when a recurring job fails or doesn't run.

This guide covers Hangfire.AspNetCore 1.8.25, the current release on NuGet (checked October 30, 2026), with Hangfire.Core of the same version. .NET and EF Core source links point to the v9.0.22 tags, the latest .NET 9 patch in both repositories on the same date. Retry counts and delays are covered in Hangfire automatic retry, jobs that never start in why a Hangfire recurring job is not running, and scoped services in a plain hosted service in .NET BackgroundService scheduled tasks.

How Hangfire.AspNetCore Activates a Job

AddHangfire builds Hangfire's global configuration from the container. Before it runs your configuration callback, it installs an AspNetCoreJobActivator built from the container's IServiceScopeFactory, so a UseActivator call inside your callback replaces it (HangfireServiceCollectionExtensions.cs). AddHangfireServer hands that activator to the server unless BackgroundJobServerOptions.Activator is already set (same file). The activator lives in the Hangfire.NetCore package, which Hangfire.AspNetCore references.

What happens for each run, from the source:

1. A new scope per execution. CoreBackgroundJobPerformer.Perform opens using (var scope = _activator.BeginScope(context)) around the whole run (CoreBackgroundJobPerformer.cs), and BeginScope returns a wrapper around _serviceScopeFactory.CreateScope() (AspNetCoreJobActivator.cs).
2. The job type is resolved from that scope. Resolve calls ActivatorUtilities.GetServiceOrCreateInstance(_serviceScope.ServiceProvider, type) (AspNetCoreJobActivatorScope.cs). That method returns the registered service, and "if one is not found then instantiate it directly", filling the constructor from the same scope. A job class doesn't have to be registered.
3. Static methods get no instance. Perform calls Resolve only when the job method isn't static. A static job method gets nothing from the container.
4. Async jobs keep the scope until their task completes. For a method that returns Task, InvokeMethod blocks until the task finishes before Perform returns (CoreBackgroundJobPerformer.cs).
5. The scope is then disposed. DisposeScope calls DisposeAsync when the scope supports it and Dispose otherwise (AspNetCoreJobActivatorScope.cs), which disposes every scoped and transient disposable resolved during the run, including the DbContext.

So the lifetimes you registered behave like this inside a job:

Each retry is another call to Perform, so it gets a new scope too. So does each occurrence of a recurring job, because each occurrence is an ordinary background job.

The Expression Stores a Type, Not Your Object

A common worry is that BackgroundJob.Enqueue(() => _mailer.SendAsync(id)) inside a controller drags the request's _mailer into the job. It doesn't. When the expression's target is a variable or field, Hangfire evaluates it only to read its runtime type and stores that type; a comment in the source says, "People consider that the whole object is serialized, this is not true" (Job.cs). At run time the worker resolves that type from the job's own scope.

The catch is which type gets stored: the concrete class behind _mailer, such as SmtpInvoiceMailer, not IInvoiceMailer. If only the interface is registered, the activator falls back to constructing the concrete class with ActivatorUtilities, not through your registration. Name the type explicitly and Hangfire stores that type instead:

// Stores IInvoiceMailer; the worker resolves it from the job's scope.
BackgroundJob.Enqueue<IInvoiceMailer>(mailer => mailer.SendAsync(invoiceId));

What "Cannot Access a Disposed Object" Means in a Job

Two messages show up, and they point at different things:

• System.ObjectDisposedException: Cannot access a disposed object. Object name: 'IServiceProvider'. Something resolved a service from a scope that had already been disposed. The container's scope checks for disposal on every GetService call and throws with the object name IServiceProvider (ServiceProviderEngineScope.cs, ThrowHelper.cs, message text).
• System.ObjectDisposedException: Cannot access a disposed context instance. Something used a DbContext after it was disposed, either by its scope or by your own code. EF Core throws this from CheckDisposed with your context's class name as the object name (DbContext.cs, CoreStrings.resx).

Because the job's own scope is always fresh, both mean the code reached outside it or outlived it. These are the causes, in the order they're usually found.

A Provider Captured From an HTTP Request

ASP.NET Core creates a scope per request and exposes it as HttpContext.RequestServices, and "in apps that process requests, scoped services are disposed at the end of the request". A job runs on a Hangfire worker after the request has returned, so anything it reaches through the request's provider is already gone.

Static job methods are where this usually starts. Hangfire's Passing Dependencies page notes that a static method is restricted to your application's static context: new, service location, factories, or singletons. A static IServiceProvider assigned from a request is the version that breaks:

// Broken: Services holds the provider of the request that last set it.
public static class ReportRunner
{
    public static IServiceProvider? Services;

    public static void Run()
    {
        var db = Services!.GetRequiredService<AppDbContext>(); // throws once that request has ended
        // ...
    }
}

// In a controller action:
ReportRunner.Services = HttpContext.RequestServices;
BackgroundJob.Enqueue(() => ReportRunner.Run());

The same failure comes from a singleton that caches a scoped service or a provider it was handed during a request. The fix is to make the job an instance method on a class that takes its dependencies in its constructor, as shown in the pattern below.

A Service Passed as a Job Argument

Arguments are not handed to the job in memory. Hangfire evaluates each argument expression when you enqueue (Job.cs) and serializes it to JSON with Newtonsoft.Json for storage, so job => job.Run(_db) never gives the job the live context you passed. Hangfire rejects delegate and expression parameters outright ("Anonymous functions, delegates and lambda expressions aren't supported in job method parameters", Job.cs), so a Func<AppDbContext> factory can't be passed either.

Pass identifiers and plain values, as Hangfire's docs recommend: "store concrete values in an application database and pass their identifiers only to your background jobs." Let the job resolve its services from its own scope.

Three parameter types are filled in by the server instead: CancellationToken, IJobCancellationToken, and PerformContext. Whatever value was stored for them, Hangfire substitutes its own when the job runs (CoreBackgroundJobPerformer.cs, SubstituteArguments). The CancellationToken it passes is linked to both the server's shutdown and the job's abort (ServerJobCancellationToken.cs), and Hangfire's Using Cancellation Tokens page says that "when state change is detected or when shutdown is requested, the corresponding cancellation token is canceled." The same page writes CancellationToken.None in the job expression, since "any CancellationToken instance can be used, it will be replaced internally just before performing a background job."

Work That Outlives the Job Method

The scope lasts exactly as long as the job method and the task it returns. Work the method starts but doesn't await keeps going after Perform has disposed the scope.

Hangfire blocks the obvious case: a job method declared async void is rejected when the job is created, with NotSupportedException "Async void methods are not supported. Use async Task instead." (Job.cs). It can't see async void code inside the method:

// Broken: List<T>.ForEach takes an Action<T>, so this lambda is async void.
// The job method can return before the sends finish, and the scope is disposed under them.
overdue.ForEach(async invoice => await mailer.SendAsync(invoice.Id));

// Also broken: nothing awaits these, so they can run after the scope is gone.
_ = auditLog.WriteAsync(runId);
Task.Run(() => db.SaveChangesAsync());

List<T>.ForEach takes an Action<T>, and Microsoft's docs warn that "an async method that returns void can't be awaited" and that its caller can't catch exceptions it throws. Use a foreach loop with await, and await every task the job starts.

This case behaves differently from the others, and the two kinds of unawaited work fail differently:

• A discarded task, like the WriteAsync and Task.Run calls above. When a method that returns a task throws, "the exception is stored in the returned task" and rethrown only when that task is awaited. Nothing awaits it, so the job method returns normally and Hangfire records the run as Succeeded: a Failed state is built only when Perform throws (Worker.cs). Nothing retries, nothing reaches the Failed page, and nothing records the exception unless your code logs it.
• An async void lambda, like the one passed to ForEach. It has no task to hold an exception. .NET posts the exception to the SynchronizationContext that was current when the lambda started or, if there was none, throws it on the thread pool, which the runtime's source notes "will result in a crash" (AsyncVoidMethodBuilder.cs). Microsoft's docs say such exceptions "are likely to cause your application to fail", and an unhandled exception in a thread causes the application to terminate in most cases. An ObjectDisposedException from a send that outlived the scope can take down the process hosting the Hangfire server, not only this job.

Disposing the Injected Context Yourself

Wrapping an injected DbContext in using disposes it while the scope still hands the same instance to everything else in that run. EF Core's error text names this cause: "disposing a context instance that was resolved from dependency injection and then later trying to use the same context instance elsewhere." Microsoft's rule is that "services should never be disposed by code that resolved the service from the container". Remove the using and let the job's scope dispose it.

A Related Error: A Second Operation on This Context

If the job class or one of its dependencies is registered as a singleton and takes a DbContext, the context is captured: resolving a scoped service from a singleton "causes the scoped service to behave like a singleton". Every run then uses that one context, including runs on other workers at the same moment. The usual symptom isn't a disposed object but EF Core's "A second operation was started on this context instance before a previous operation completed" (CoreStrings.resx), because a DbContext is not thread-safe. In the Development environment you get an earlier error instead: there, by default, "resolving a service from another service with a longer lifetime throws an exception" (scope validation), so the shared-context error shows up where that check isn't on. Task.WhenAll over several queries on one injected context fails the same way. Register job classes as scoped or transient, or leave them unregistered.

Why the Same Exception Comes Back on Every Run

A fresh scope per run doesn't help when the bug is in the wiring. The static field in the example above still points at the disposed provider on the next attempt, and on the attempt after that, until the process restarts or another request overwrites it. Nothing changes between attempts, so the retries can't succeed:

1. The first attempt throws ObjectDisposedException. Hangfire wraps it in JobPerformanceException ("An exception occurred during performance of the job.") on the way out of the performer (CoreBackgroundJobPerformer.cs).
2. The global AutomaticRetry filter turns that failure into a scheduled retry, 10 times by default, with delays that add up to more than four hours. The schedule is in Hangfire automatic retry.
3. Every retry fails the same way. After the last one, the worker unwraps the wrapper and stores a Failed state whose exception is the original ObjectDisposedException and whose reason is the wrapper's message (Worker.cs).
4. The job stays on the dashboard's Failed page, which shows the stored exception type, message, and details with the stack trace (FailedState.cs, FailedJobsPage.cshtml). Hangfire's docs say a failed job "will not be expired unless you delete it explicitly".

A recurring job repeats this at every occurrence, each with its own retry chain; Hangfire automatic retry covers how those chains overlap. Requeueing one from the dashboard doesn't help until the code is fixed and deployed.

Unawaited work doesn't follow this pattern, as described above: a discarded task leaves the run Succeeded, with nothing retried and nothing on the Failed page, and an exception from an async void lambda isn't stored in any task and can crash the process.

Patterns That Work

Inject Scoped Services Into the Job Class

Put the work in an instance method, take the DbContext and other services in the constructor, and register the recurring job with the generic AddOrUpdate<T> so Hangfire stores the job type:

using Hangfire;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("App")));

builder.Services.AddHangfire(config => config
    .UseSqlServerStorage(builder.Configuration.GetConnectionString("Hangfire")));
builder.Services.AddHangfireServer();

var app = builder.Build();

app.Services.GetRequiredService<IRecurringJobManager>().AddOrUpdate<InvoiceReminderJob>(
    "invoice-reminders",
    job => job.RunAsync(CancellationToken.None), // replaced at run time; canceled on shutdown or a job state change
    "0 9 * * *");

app.Run();

public sealed class InvoiceReminderJob(AppDbContext db, ILogger<InvoiceReminderJob> logger)
{
    public async Task RunAsync(CancellationToken cancellationToken)
    {
        var overdue = await db.Invoices
            .Where(invoice => invoice.DueAtUtc < DateTime.UtcNow && !invoice.ReminderSent)
            .ToListAsync(cancellationToken);

        foreach (var invoice in overdue)
        {
            invoice.ReminderSent = true;
        }

        await db.SaveChangesAsync(cancellationToken);
        logger.LogInformation("Marked {Count} overdue invoices for reminders.", overdue.Count);
    }
}

AppDbContext stands for your EF Core context with an Invoices set. InvoiceReminderJob isn't registered, so the activator constructs it for each run and gives it that run's AppDbContext. The method returns a Task, so the scope stays open until SaveChangesAsync completes. The schedule is evaluated in UTC; Hangfire cron expressions and time zones covers the alternatives. The packages are the same ones that post installs, plus your EF Core provider.

Use a DbContext Factory for Parallel or Batched Work

When one run needs several contexts at once, or a fresh change tracker per batch, inject a factory instead of a context. AddDbContextFactory registers IDbContextFactory<T>, and each context you create from it is yours to dispose:

builder.Services.AddDbContextFactory<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("App")));

public sealed class RegionalTotalsJob(IDbContextFactory<AppDbContext> contexts)
{
    public async Task RunAsync(CancellationToken cancellationToken)
    {
        string[] regions = ["eu", "us", "apac"];

        await Task.WhenAll(regions.Select(async region =>
        {
            await using var db = contexts.CreateDbContext(); // one context per parallel branch
            var total = await db.Orders
                .Where(order => order.Region == region)
                .SumAsync(order => order.Amount, cancellationToken);
            // ... store total
        }));
    }
}

Here the job owns each context, so disposing it with await using is correct, unlike an injected one. AddDbContextFactory also registers the context type itself as a scoped service, as its source comment and registration code show (EntityFrameworkServiceCollectionExtensions.cs, registration), so jobs that take AppDbContext directly keep working.

Keep Arguments Small and Re-read State in the Job

Enqueue with IDs, load current rows inside the job, and design the work so that running it twice is harmless, since retries and restarts repeat it. Idempotent scheduled jobs covers that design, and Hangfire automatic retry covers which exceptions are worth retrying at all. ObjectDisposedException from wiring never is: if one keeps a long retry chain alive, [AutomaticRetry(Attempts = 0)] on that job sends it to Failed on the first attempt while you fix the code.

See the Failure From Outside Hangfire With CronRadar

The dashboard's Failed page shows the exception, but only to someone who opens it, and a run that never starts leaves nothing there. CronRadar watches each recurring job's schedule from outside the process. The CronRadar.Hangfire package discovers recurring jobs and reports their runs:

dotnet add package CronRadar.Hangfire

using CronRadar.Hangfire;

// Alongside builder.Services.AddHangfire(...) and AddHangfireServer().
builder.Services.AddCronRadarHangfire();

Set CRONRADAR_API_KEY in the host's environment or secret store rather than in a committed file. Package status, checked October 30, 2026: NuGet installs CronRadar.Hangfire 0.1.0, which can report a failure before Hangfire finishes retrying, including cancellations; reporting only after retries are exhausted requires the pending 0.2.1 release. In 0.1.0, from its source at the release tag:

• AddCronRadarHangfire() adds a global Hangfire server filter, runs a registry reconcile at startup, and registers a recurring job, cronradar:reconcile, that repeats it every 15 minutes by default. That job's class isn't registered in DI, so AspNetCoreJobActivator constructs it through the same GetServiceOrCreateInstance fallback described above.
• For each run of a recurring job, the filter reports start before the method runs. Afterwards it reports complete if the run threw nothing and wasn't canceled, and fail otherwise. One-time background jobs are skipped, and [SkipMonitor] on a method opts it out.

For the errors in this guide, that means:

• A recurring job's wiring error alerts on the first attempt. Because 0.1.0 reports every failed attempt of a recurring job, the first ObjectDisposedException is a fail, and CronRadar records failed and opens an incident immediately (concepts), hours before Hangfire's retry chain ends. Each later retry reports fail again. One-time jobs, such as the static BackgroundJob.Enqueue example above, aren't reported at all.
• The message is Hangfire's wrapper. The filter sends the message of the exception Hangfire gives server filters, which is the JobPerformanceException ("An exception occurred during performance of the job.") rather than the ObjectDisposedException inside it (BackgroundJobPerformer.cs). Open the job on Hangfire's Failed page for the real exception.
• A discarded task reports success. The method returned normally, so 0.1.0 reports complete. 0.1.0 has no way to report outcome values, so CronRadar can't tell that the run skipped its work.
• A run that never happens still alerts. If no run reports by the expected time, the monitor goes from healthy to warning during the grace period and to critical after it, for example because the Hangfire server is down.

Alerts go to email, Slack, a webhook, Discord, or PagerDuty. Jobs with noisy transient failures will alert on attempts that later succeed until 0.2.1 ships; Hangfire automatic retry covers how retry settings change that, and Hangfire monitoring covers what to check inside Hangfire itself.

Frequently Asked Questions

Does Hangfire create a new DbContext for each job?

Yes, if the context is registered as scoped, which AddDbContext does by default. Hangfire.AspNetCore creates a DI scope for every execution, resolves the job class from it, and disposes it when the method or its returned task finishes. Each retry and each recurring occurrence gets its own scope and its own context.

Why does my Hangfire job throw "Cannot access a disposed object"?

The job reached a service that belongs to a scope that was already disposed. Usually that is a provider or service captured during an HTTP request and reached later from a static method or a singleton. Otherwise, the job disposed its own injected DbContext, or started work it didn't await that ran after the job's scope was disposed. Hangfire's own scope is always fresh, so look for code that reaches outside it or outlives it.

Can I inject a scoped service into a Hangfire job?

Yes. Take it in the job class's constructor and enqueue or register the job with the generic overload, such as AddOrUpdate<InvoiceReminderJob>(...). The class doesn't need to be registered; if it is, register it as scoped or transient, because a singleton job keeps one context for the life of the process.

Can I pass a DbContext or another service as a Hangfire job argument?

No. Arguments are serialized to JSON when the job is created, so the job never receives the live object, and delegate parameters such as a factory function are rejected. Pass IDs and plain values, and let the job resolve services from its own scope.

Why does the error happen on every retry?

Each retry gets a new scope, but the cause is in the code: a static field still points at the same disposed provider, or the same disposing code runs again. All 10 default retries fail the same way, and the job ends on the Failed page with the original ObjectDisposedException. Fix the code and deploy; requeueing won't help.

This guide covers @nestjs/schedule 12.0.2, the current release on npm (checked October 30, 2026), which depends on cron 4.4.0 (package.json). The node-cron and node-schedule packages are covered in Node.js cron monitoring. Queue-backed repeatable jobs are in BullMQ repeatable jobs.

Registering the Scheduler

Import ScheduleModule.forRoot() in the root module. The task scheduling docs say to call forRoot() in one module only: each additional import registers every @Cron(), @Interval(), and @Timeout() handler again, so each job runs once per import.

import { Module } from '@nestjs/common'
import { ScheduleModule } from '@nestjs/schedule'

@Module({
  imports: [ScheduleModule.forRoot()],
})
export class AppModule {}

forRoot() accepts three booleans, cronJobs, intervals, and timeouts, all true by default (schedule.module.ts, schedule-module-options.interface.ts). With one set to false, the explorer skips that kind of handler (schedule.explorer.ts). The scheduler mounts timeouts, intervals, and cron jobs in onApplicationBootstrap and clears them in beforeApplicationShutdown (scheduler.orchestrator.ts).

@Cron, @Interval, and @Timeout

import { Injectable, Logger } from '@nestjs/common'
import { Cron, CronExpression, Interval, Timeout } from '@nestjs/schedule'

@Injectable()
export class TasksService {
  private readonly logger = new Logger(TasksService.name)

  @Cron(CronExpression.EVERY_DAY_AT_2AM, {
    name: 'nightly-report',
    timeZone: 'Europe/Paris',
    waitForCompletion: true,
  })
  async nightlyReport() {
    this.logger.log('Building the report')
  }

  @Interval('cache-refresh', 10000)
  refreshCache() {}

  @Timeout(5000)
  warmUp() {}
}

• @Cron(cronTime, options) takes a cron string, a JavaScript Date, or a Luxon DateTime (cron.decorator.ts). A Date runs the method once at that moment. Cron strings have five fields, or six with seconds first (docs).
• @Interval(name?, ms) calls setInterval(), and @Timeout(name?, ms) calls setTimeout() once, counted from application startup. The name is optional and only needed to reach the timer through SchedulerRegistry.

The CronOptions type at 12.0.2 defines these options (cron.decorator.ts):

Without a timeZone or utcOffset, cron 4.4.0 uses the system time zone (time.ts, README). For how that interacts with daylight saving, see cron time zones.

CronExpression Mixes Five- and Six-Field Strings

The enum is a set of string constants, and they do not share one format (cron-expression.enum.ts):

Both forms run correctly in Nest. The difference matters when you copy the schedule into another tool that expects five fields, such as a monitor.

What Happens When a Handler Throws

The explorer wraps every declarative @Cron(), @Interval(), and @Timeout() method before it is scheduled (schedule.explorer.ts):

private wrapFunctionInTryCatchBlocks(methodRef: Function, instance: object) {
  return async (...args: unknown[]) => {
    try {
      await methodRef.call(instance, ...args);
    } catch (error) {
      this.logger.error(error);
    }
  };
}

Because the method is awaited, both a synchronous throw and a rejected promise land in the catch. The error is logged through Nest's Logger and goes nowhere else: the process keeps running, the job stays scheduled, and the next tick runs as usual. Nothing outside the log records that the run failed.

Jobs added with SchedulerRegistry.addCronJob() also get a Nest try/catch, but it wraps the CronJob's fireOnTick, not your callback. In cron 4.4.0, fireOnTick catches callback errors first and sends them to the job's errorHandler if one is set, or to console.error('[Cron] error in callback', error) otherwise, so they do not reach Nest's Logger (scheduler.registry.ts, job.ts).

Two Ways a Tick Is Skipped Without an Error

Both happen inside cron 4.4.0 (job.ts):

• waitForCompletion: true returns early from a tick while the previous run is in progress. Without it, an async handler's promise is not awaited, so a slow run and the next tick overlap. The flag only knows about runs in its own process. For overlap in general, see prevent overlapping cron jobs.
• A late tick past threshold is dropped. When the timer fires more than 250 ms late (the option's doc comment in cron.decorator.ts blames slow or busy hardware), cron logs a warning ending in "Skipping execution as it exceeds threshold (250ms)." and does not run the job. Within the threshold, it logs a warning and runs it immediately.

SchedulerRegistry

Inject SchedulerRegistry to control named jobs at runtime (docs, scheduler.registry.ts):

import { Injectable } from '@nestjs/common'
import { SchedulerRegistry } from '@nestjs/schedule'
import { CronJob } from 'cron'

@Injectable()
export class JobsAdmin {
  constructor(private readonly schedulerRegistry: SchedulerRegistry) {}

  pauseReport() {
    const job = this.schedulerRegistry.getCronJob('nightly-report')
    job.stop()
    return job.lastDate() // Date of the last run, or null
  }

  addCleanup() {
    const job = new CronJob('0 3 * * *', () => {
      // errors here go to cron's console.error, not Nest's Logger
    })
    this.schedulerRegistry.addCronJob('cleanup', job)
    job.start()
  }
}

getCronJobs() returns a Map of name to CronJob. nextDate() returns a Luxon DateTime and throws if a job has no future run. Intervals and timeouts have matching getInterval, addInterval, deleteInterval, getTimeout, addTimeout, and deleteTimeout methods.

Every Replica Runs Every @Cron

The scheduler is an in-process timer, so there is no shared state between instances. The NestJS docs state it directly: "The scheduler runs every job in every process of your application." With three instances behind a load balancer, a @Cron('0 2 * * *') job runs three times a night (task scheduling docs). Each Kubernetes replica or cluster worker is its own process, so each one fires the job. Distributed cron covers the general problem.

Running a Job on One Instance

The documented answer is @nestjs/locks, at 0.0.5 on npm (checked October 30, 2026). Add @OnOneInstance() next to the @Cron():

import { Injectable } from '@nestjs/common'
import { OnOneInstance } from '@nestjs/locks'
import { Cron } from '@nestjs/schedule'

@Injectable()
export class InvoicesJob {
  @Cron('0 2 * * *')
  @OnOneInstance({ key: 'invoices:nightly-export' })
  async exportInvoices() {
    // ...
  }
}

What the Distributed locks page documents:

• The instances share a lock store, such as your PostgreSQL database or Redis. The page shows how to register LocksModule and the store.
• The first instance to fire the job takes a lease and keeps renewing it. On the other instances, the call resolves without running the method.
• When the owner dies, its lease expires after ttl (default '30s'), and the next instance to tick takes the job over. Ticks during that window are skipped, and "Missed ticks aren't caught up".
• @WithoutOverlapping() skips a tick while a previous run is still going on any instance.

The same page explains why the usual fixes fall short. A single RUN_JOBS=true instance "works until a rolling deploy has two of them for a minute", and waitForCompletion: true "stops a job from overlapping itself, on one instance". Turning jobs off with forRoot({ cronJobs: false }) on all but one instance is the same flag approach. Either way, write the job so a second run does no harm, as in idempotent scheduled jobs.

Reporting Each Run to CronRadar

The scheduler logs errors and keeps going, and a skipped or missed tick logs at most a warning. An external check-in turns each run into a record, and a missing record into an alert.

The CronRadar Node.js SDK is temporarily unavailable: the published package cannot load because it is missing a required file. Report over HTTP instead. HTTP check-ins do not discover jobs automatically, so each @Cron() method needs its own monitor key and its schedule.

This helper uses the built-in fetch with a five-second timeout and Basic authentication, with the API key as the username and an empty password. Monitoring errors are logged and never change the job's result. The job's own error is rethrown, so Nest's wrapper still logs it:

import { randomUUID } from 'node:crypto'

const CRONRADAR_PING_URL = 'https://cron.life/api/v1/ping'

async function report(
  monitorKey: string,
  event: 'start' | 'complete' | 'fail',
  params: Record<string, string>,
): Promise<void> {
  const apiKey = process.env.CRONRADAR_API_KEY
  if (!apiKey) return

  const query = new URLSearchParams(params).toString()
  const url = `${CRONRADAR_PING_URL}/${encodeURIComponent(monitorKey)}/${event}?${query}`

  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: { Authorization: `Basic ${Buffer.from(`${apiKey}:`).toString('base64')}` },
      signal: AbortSignal.timeout(5000),
    })
    if (!response.ok) console.error(`CronRadar returned ${response.status} for ${monitorKey}`)
  } catch (error) {
    console.error(`CronRadar ${event} report failed for ${monitorKey}: ${(error as Error).message}`)
  }
}

export async function monitored(
  monitorKey: string,
  schedule: string,
  task: () => Promise<void>,
): Promise<void> {
  const runId = randomUUID()
  await report(monitorKey, 'start', { schedule, run_id: runId })
  try {
    await task()
  } catch (error) {
    // Keep the message generic: error details can contain data that must not leave the app.
    await report(monitorKey, 'fail', {
      run_id: runId,
      message: `${monitorKey} threw ${(error as Error).name}`,
    })
    throw error
  }
  await report(monitorKey, 'complete', { run_id: runId })
}

Call it inside the method body, after the decorators:

import { Injectable } from '@nestjs/common'
import { OnOneInstance } from '@nestjs/locks'
import { Cron } from '@nestjs/schedule'
import { monitored } from './cronradar'

@Injectable()
export class InvoicesJob {
  @Cron('0 2 * * *', { name: 'invoice-export', timeZone: 'UTC' })
  @OnOneInstance({ key: 'invoices:nightly-export' })
  async exportInvoices() {
    await monitored('invoice-export', '0 2 * * *', () => this.runExport())
  }

  private async runExport() {
    // ...
  }
}

Because @OnOneInstance() skips the method on instances that do not hold the lease, only the instance that runs the job reports it.

CronRadar reads schedules as standard five-field cron and evaluates them in UTC (schedules). Run the job in UTC and send the same expression. For a six-field CronExpression constant, drop the seconds field: 0 */5 * * * * becomes */5 * * * *. A job that runs more than once a minute, such as EVERY_30_SECONDS, has no five-field form.

The start report carries the schedule, so CronRadar creates the monitor the first time it sees the key. A fail report opens an incident immediately. A start without a completion, and a run that never arrives, are caught against the schedule, which covers the thrown error Nest only logs, the skipped tick, and the instance that stopped. Alerts go to email, Slack, webhook, Discord, or PagerDuty. Keep CRONRADAR_API_KEY in your deployment's secret store or an environment file that is not committed, and use a separate CronRadar application for each environment. Set the grace period to cover the job's usual duration.

Frequently Asked Questions

Why does my NestJS cron job run twice?

Either more than one process is running the app, or ScheduleModule.forRoot() is imported in more than one module. The scheduler runs every job in every process, and each extra forRoot() import registers every handler again. Cron job running twice covers the other causes.

Does an exception in a @Cron method crash the app?

No. Declarative @Cron(), @Interval(), and @Timeout() methods are wrapped in a try/catch that logs the error through Nest's Logger. The job stays scheduled, and nothing outside the log records the failure.

Does waitForCompletion work across instances?

No. It skips a tick only while the same CronJob, in the same process, is still running its previous callback. Across instances, use @WithoutOverlapping() from @nestjs/locks.

What time zone does @Cron use by default?

The system time zone of the process. Pass timeZone (an IANA name such as 'Europe/Paris') or utcOffset, but not both.

Can CronRadar discover NestJS jobs automatically?

No. The Node.js SDK is temporarily unavailable, and HTTP check-ins do not discover jobs. Report each job with its own monitor key and five-field UTC schedule.

This guide covers cron 4.4.0, node-cron 4.6.0, node-schedule 2.1.2, croner 11.0.0, Agenda 6.2.6, and BullMQ 6.5.2, each the current release on the npm registry (checked October 30, 2026). For error handling, restarts, and overlaps in node-cron and node-schedule, see Node.js cron job monitoring; for BullMQ Job Schedulers in depth, see BullMQ repeatable jobs and Job Schedulers. The .NET equivalent of this comparison is Hangfire vs Quartz.NET vs BackgroundService.

Two Models: Timers in the Process, or Jobs in a Store

The first four libraries are timers. You call a function with a cron pattern, the library sets a timer for the next match, and the job is a JavaScript object. node-schedule's README says it plainly: jobs "will only fire as long as your script is running, and the schedule will disappear when execution completes" (README at v2.1.2). croner "operates in-memory, with no need for a database" (README at 11.0.0), and node-cron "coordinates but does not persist state to a database" (README at v4.6.0).

Agenda and BullMQ are job systems. The schedule is a record in a store, workers poll or subscribe to it, and the process that runs a job need not be the one that created the schedule. Agenda 6 has pluggable backends for MongoDB, PostgreSQL, and Redis, each a separate package (README at agenda@6.2.6). A BullMQ Job Scheduler lives in Redis, the default backend, or in PostgreSQL with the optional PostgreSQL backend (PostgreSQL backend guide at v6.5.2), and produces each run as a job that waits in the delayed state until it is due (Job Schedulers docs).

Node.js Schedulers at a Glance

Cron Dialects Differ More Than They Look

All six accept a five-field crontab pattern, but the same string does not always mean the same thing.

Day-of-month and day-of-week. In standard cron, 0 9 1 * 1 runs on the 1st of the month and on every Monday: when both day fields are restricted, a match on either one is enough (crontab(5)). croner keeps that OR logic by default and offers +MON or { domAndDow: true } for AND (README at 11.0.0). node-cron 4.6.0 combines the two fields with AND: both must match (README at v4.6.0). A pattern moved from crontab to node-cron can run on far fewer days. Avoid restricting both fields when a schedule has to be portable.

Seconds. A six-field pattern puts seconds first in cron, node-cron, node-schedule, croner, and BullMQ. kelektiv's cron defaults a missing seconds field to 0 (README at v4.4.0), and croner's mode option can force 5-, 6-, or 7-part parsing instead of detecting it (README at 11.0.0).

Weekday numbers. node-cron borrows L, W, #, and ? from Quartz but keeps standard weekday numbering (1 is Monday), so Quartz expressions do not carry over unchanged (README at v4.6.0). croner switches to Quartz numbering only with alternativeWeekdays: true (README at 11.0.0). In kelektiv's cron 4.x, months are numbered 1-12; the README's migration section notes they were 0-11 before (README at v4.4.0).

For the fields themselves, see cron expression syntax.

Time Zones and Daylight Saving Time

kelektiv's cron runs in local time unless you pass timeZone (README at v4.4.0). BullMQ passes its repeat options, including tz, to cron-parser (job-scheduler.ts), and cron-parser 5.10.2, the version bullmq 6.5.2 depends on, uses the process's local zone when no zone is given (CronDate.ts). Set tz as a repeat option; the BullMQ guide has more. Set the zone explicitly in every library.

The documented daylight saving behavior differs:

• node-cron: in a fall-back the repeated hour runs once, so a */15 schedule can pause for up to the length of the shift. The README recommends timezone: 'UTC' for an uninterrupted interval (README at v4.6.0).
• croner: fixed-time jobs such as 0 30 2 * * * run once at the first occurrence of a repeated time and, for a time that doesn't exist, at the first valid time after the gap. Interval jobs run on both occurrences of a repeated time and skip times that don't exist (README at 11.0.0).

The general problem is covered in cron and daylight saving time. Running in UTC avoids it.

What Happens After a Restart or Downtime

For the four in-process libraries, a run that falls due while the process is down never happens, and nothing records that it didn't. The late-run features cover a running process that woke up late: kelektiv's threshold decides whether a late tick still runs (README at v4.4.0), and node-cron emits execution:missed for each slot its timer woke more than missedExecutionTolerance (1000 ms by default) after (scheduled-task.ts, plan-beat.ts at v4.6.0).

Agenda's every() saves a single job record for the name (type = 'single' in index.ts) and computes the next run from lastRunAt with cron-parser (nextRunAt.ts). Because there is one record with one next run time, missed runs cannot pile up as separate jobs. BullMQ behaves similarly: the overdue job runs once, late, and the next run is calculated from the current time, for a pattern the next occurrence after now (job-scheduler.ts at v6.5.2) and for every on Redis the next slot after now (getJobSchedulerEveryNextMillis.lua). The BullMQ guide covers this in depth.

Neither replays every missed slot. If each slot matters, for example a report per day, make the job find and process the gap itself; see missed runs after downtime.

Overlap and Multiple Instances

Three in-process libraries can skip a run while the previous one is still going: waitForCompletion in kelektiv's cron, noOverlap in node-cron, and protect in croner. node-schedule has none, so track a running flag yourself (example). These options work within one process only. Two instances of the app are two schedulers, and each runs every job; see preventing overlapping cron jobs for locks that span processes.

node-cron 4.6.0 is the only in-process library here with built-in coordination: distributed: true makes one instance run each firing, using an environment-variable flag by default or a Redis coordinator for high availability (README at v4.6.0). Agenda and BullMQ coordinate through their store by design. For the patterns behind all of this, see distributed cron.

How to Choose

• One instance, missed runs tolerable, standard crontab patterns: kelektiv's cron or croner. croner adds L, W, #, a year field, and documented DST rules, and keeps standard OR semantics for day fields.
• One instance now, several later, without a database: node-cron 4, for noOverlap, distributed, and lifecycle events. Remember its AND rule for day-of-month plus day-of-week.
• Calendar-style rules more than cron strings: node-schedule's RecurrenceRule, with an error listener on every job (why).
• Schedules must survive deploys and run on one of many workers: Agenda on MongoDB, PostgreSQL, or Redis, or BullMQ on Redis or PostgreSQL. BullMQ if you need a work queue too.

Monitoring Whichever You Pick

None of these libraries can tell you about a run that never started: a stopped process, a worker that never came up, or a schedule removed from the store all fail without an error. An outside monitor that knows the schedule catches those.

CronRadar's cronradar npm package is unavailable, so Node.js jobs report over HTTP check-ins. Check-ins do not discover jobs automatically: each job reports with its own monitor key and its schedule. The Node.js monitoring guide has a monitored(monitorKey, schedule, task) wrapper that sends start, complete, and fail check-ins with HTTP Basic authentication (the API key as the username, empty password), a five-second timeout, and the key read from CRONRADAR_API_KEY in the environment. It wraps any job function, so it works the same way with each library:

const { Cron } = require('croner')

// monitored() is the wrapper from the Node.js monitoring guide
new Cron(
  '0 3 * * *',
  { timezone: 'UTC', protect: true },
  monitored('nightly-backup', '0 3 * * *', performBackup),
)

const { CronJob } = require('cron')

CronJob.from({
  cronTime: '0 3 * * *',
  onTick: monitored('nightly-backup', '0 3 * * *', performBackup),
  timeZone: 'UTC',
  waitForCompletion: true,
  start: true,
})

For BullMQ, check in from the worker's processor, as shown in the BullMQ guide.

CronRadar reads schedules as standard five-field cron evaluated in UTC (schedule syntax). Run the job in UTC and send a five-field pattern: drop a leading seconds field (0 0 2 * * * becomes 0 2 * * *). Five fields cannot express L or W, so schedule such a job on every candidate date and let it decide whether to do the work.

A monitor is pending until its first check-in and healthy while runs arrive. A late run is warning inside its grace period and critical once grace expires; a failure check-in makes it critical straight away. Alerts go to email, Slack, webhook, Discord, or PagerDuty.

Frequently Asked Questions

What is the difference between cron and node-cron on npm?

They are separate projects. cron is maintained in the kelektiv/node-cron repository and exports CronJob; node-cron is maintained in the node-cron/node-cron repository and exports schedule(). Their dialects and options differ: for example, node-cron combines day-of-month and day-of-week with AND.

Which Node.js scheduler supports seconds?

cron, node-cron, node-schedule, croner, and BullMQ document an optional seconds field at the front of a six-field pattern, and croner also accepts a seventh field for the year. Agenda passes cron patterns to cron-parser.

Which Node.js schedulers keep jobs across restarts?

Agenda, which stores jobs in MongoDB, PostgreSQL, or Redis, and BullMQ, which stores Job Schedulers in Redis or PostgreSQL. cron, node-cron, node-schedule, and croner keep schedules in memory and lose them when the process stops.

Do Agenda and BullMQ run every missed job after downtime?

No. Each keeps one pending run per schedule, so after downtime the overdue run happens once and the next is calculated from there. Make the job process the missed period itself if every slot matters.

Does CronRadar integrate with node-cron, croner, Agenda, or BullMQ?

No. The Node.js SDK is unavailable, and CronRadar does not discover Node.js jobs. Each job reports through HTTP check-ins with its own monitor key and schedule.

This guide covers heartbeat checks only, not alert routing, on-call schedules, or other Opsgenie features. It covers Opsgenie's Heartbeat API v2 and the heartbeat endpoints of the Jira Service Management Cloud operations REST API, whose URLs use v1, the only version available, as documented in the Opsgenie API docs and on Atlassian's developer site (checked October 30, 2026). The dead man's switch explains the heartbeat pattern itself.

Atlassian's Opsgenie Dates

Both dates come from Atlassian's announcement of March 3, 2025, which points customers who want to keep their alert and on-call workflows to Jira Service Management. Atlassian's integration changes page names Compass as the other destination. This guide covers the Jira Service Management side.

How Opsgenie Heartbeats Work

A Named Interval, Reset by Every Ping

A heartbeat is a unique, case-sensitive name and an interval. The Heartbeat API takes interval (minimum 1), intervalUnit (minutes, hours, or days), and enabled, and the heartbeat guide says each heartbeat can be checked "up to once per minute." The interval runs from the last ping. With a 10-minute interval, "If a Heartbeat request is not received for more than 10 minutes," Opsgenie creates an alert. The API has no schedule or time-zone field: Opsgenie never knows when a run is due, only how long it has been since the last ping.

On expiry, Opsgenie creates an alert "soon after," using the heartbeat's alertMessage, alertTags, and alertPriority. Left unset, the priority is P3 and the message is the heartbeat's name followed by "is expired" (Heartbeat API), and every expiry alert carries the Heartbeat tag by default. The next ping makes the heartbeat active again, and "the expiry alert will be automatically closed soon after." Heartbeats are available on Opsgenie's Standard and Enterprise plans only (heartbeat guide).

Pinging a Heartbeat

The API ping is a GET, POST, PUT, or PATCH to https://api.opsgenie.com/v2/heartbeats/:heartbeatName/ping with an Authorization: GenieKey header; EU accounts use api.eu.opsgenie.com. Opsgenie processes pings asynchronously and answers PONG - Heartbeat received without checking that the heartbeat exists, so a misspelled name gets the same answer as a real one (Heartbeat API).

The heartbeat guide lists the other ways in: the Lamp command-line tool (lamp heartbeat), the Opsgenie Java API, the Script Monitoring Client, an email to the heartbeat's built-in address, and Auto Heartbeat Creation, an opt-in setting that, once enabled, creates and pings a heartbeat when a ping names one that doesn't exist, provided the API key belongs to a team.

What a Heartbeat Can't Report

The Heartbeat API's operations are ping, add, get, list, update, delete, enable, and disable. A ping carries only the name: no start event, no failure, no exit status. A run that fails before it pings looks the same as one that never started, and so does a run that hangs; each is reported only when the interval runs out.

Heartbeats in Jira Service Management

What the Migration Moves

From Atlassian's notes on advanced alert configurations after migration:

• Heartbeats move automatically, but heartbeat monitoring "isn't available in Jira Service Management Free and Standard plans," only Premium and Enterprise (feature changes).
• Heartbeats on the deprecated v1 version aren't moved. Recreate them by hand with Jira Service Management's API.
• Heartbeats belong to teams, under Teams > Operations > Heartbeats. A site holds 2,000; a migrated total over the cap still moves, but you must remove the excess before adding more.
• Email ping addresses move from opsgenie.net to atlassian.net. Update scripts that email the old address; Copy heartbeat name in the heartbeat's Actions menu copies the new one.

Atlassian's feature changes and deprecations list adds two things. Heartbeats have moved to a team-based configuration, which you switch on by hand in Opsgenie under Settings > General > Heartbeat Configuration > Activate Heartbeat, before or after migration. And Opsgenie REST API endpoints have to be updated to Jira Service Management's, with Opsgenie's API key management replaced by Atlassian authentication.

Same Model, New Endpoint and Credentials

Jira Service Management describes the same check: heartbeats are expected at an interval set in minutes, hours, or days, and if one "is not received within a specified time frame," it generates an alert (What are heartbeats?). A heartbeat is Pending before its first ping, Responsive while pings arrive, Unresponsive after a silence "far beyond the expected interval," and Off when turned off for maintenance. Neither that page nor the Heartbeats API says whether the interval counts from the last ping, as Opsgenie's guide does, so the alert times worked out below are Opsgenie's; check Jira Service Management's on a test heartbeat before relying on them.

The ping moves to a team-scoped URL. This is the documented request, adapted to read the credential from a file and the IDs from the environment, and to give up after five seconds:

# JSM_AUTH holds "email:api_token" and is read from a file only the job's account can read.
# JSM_CLOUD_ID and JSM_TEAM_ID are the {cloudId} and {teamId} path parameters.
JSM_AUTH=$(cat /etc/jsm/heartbeat-auth)
curl --fail --silent --show-error --max-time 5 --output /dev/null \
  --request POST --user "$JSM_AUTH" \
  "https://api.atlassian.com/jsm/ops/api/$JSM_CLOUD_ID/v1/teams/$JSM_TEAM_ID/heartbeats/ping?name=nightly-backup"

GET, PUT, and PATCH work too. The Heartbeats API lists the scopes read:ops-config:jira-service-management and write:ops-config:jira-service-management, answers 202 with PONG - Heartbeat received, and, like Opsgenie, doesn't check that the heartbeat exists.

The credential is the larger change. The reference authenticates with an Atlassian account's email and API token, not an integration's GenieKey, and Atlassian API tokens expire after 1 to 365 days, one year by default (API tokens). Every host that pings needs the token, and a new one before it expires; when it lapses, pings stop resetting the heartbeats that depend on it. Atlassian's tracker has a suggestion to allow GenieKey pings, JSDCLOUD-18241, unresolved and in Gathering Interest status (checked October 30, 2026).

Converting an Interval to a Cron Schedule Plus Grace

What Each Model Waits For

An interval heartbeat alerts when the time since the last ping exceeds the interval. A CronRadar monitor goes critical, with last result timeout, an incident, and an alert, when the run due at a scheduled time hasn't checked in by that time plus a grace period; how CronRadar applies the grace period has the timing rules.

The consequence for intervals: an interval has to be longer than the longest normal gap between pings, and a skipped run is caught only if the gap it leaves is longer than the interval. On a job with even gaps, that means an interval under two periods. On a job with uneven gaps, some skipped runs never alert. And because the interval counts from the previous ping, the alert time for a skipped run moves with how long the previous run took.

Five Jobs, Both Ways

Each job below sends its heartbeat when it finishes. Opsgenie creates its alert "soon after" expiry, so its times are the earliest possible. CronRadar times use a completion check-in and the grace shown.

For a job with a fixed period and a steady run time, a grace of the interval minus the period plus the run time reproduces Opsgenie's alert time: 90 minus 60 plus 5, or 35 minutes, for the hourly job. A grace sized from the job is usually shorter, because a cron monitor knows when each run is due; choosing a grace period works through the measurements, including how a start check-in shrinks the grace to the start delay.

Write the Schedule From the Job

An interval doesn't record when the job runs, so take the schedule from the crontab or scheduler. CronRadar reads five-field cron in UTC, with no seconds field, @daily-style shortcuts, L, W, #, ?, or 7 for Sunday, and when both day fields are restricted it expects a run only on dates that match both (schedule syntax). Convert local times to UTC. If the scheduler follows daylight saving time, use the earlier of the two UTC times and a grace of at least an hour plus the job's usual duration. Dead Man's Snitch vs CronRadar has more conversions and covers jobs that run any time within a window.

What Maps Across

A check-in needs schedule only to create a missing monitor (API reference), and CronRadar applies a check-in's schedule and gracePeriod only at that moment; change an existing monitor's values in its settings. The alert sequence and acknowledgment are in the verification guide.

An Opsgenie ping can't report a start or a failure; a CronRadar check-in can also be start or fail, and a fail opens an incident at once (concepts). Dead Man's Snitch vs CronRadar covers the lifecycle events, stuck runs, and outcome values, and cron job alerting covers which of them deserve an alert.

CronRadar Has No Opsgenie or Jira Service Management Channel

CronRadar can't send alerts into Opsgenie or Jira Service Management. Its alert channels are email, Slack, webhook, Discord, and PagerDuty, connected per application in its Alerts tab. It has no on-call schedules, escalation policies, or SMS. To decide which migrated heartbeats belong on PagerDuty and which on Slack, email, or a ticket webhook, use the priority classes in the CronRadar Scheduled Job Methodology.

Jira Service Management's integration named Webhook doesn't close that gap: Atlassian documents it as "an outgoing integration" that posts Jira Service Management alert actions to a URL you give it (Integrate with Webhook). It doesn't receive webhooks, and CronRadar's webhook payload hasn't been verified against any Jira Service Management incoming integration. If a heartbeat's alerts have to arrive in Jira Service Management, keep that heartbeat in Jira Service Management.

CronRadar's Free plan covers 10 active monitors with every alert channel and no card; beyond that, Grow bills each further monitor monthly by schedule class (pricing).

Migration Checklist: Run Old and New in Parallel

1. Export the Heartbeat List

The list request returns each heartbeat's name, interval, unit, enabled flag, owner team, and alert fields (Heartbeat API). It needs an API integration that isn't restricted to access configurations; a restricted one can only ping.

# The integration's key, read from a file only this account can read.
OPSGENIE_API_KEY=$(cat /etc/opsgenie/api-key)
curl --fail --silent --show-error --max-time 10 \
  --header "Authorization: GenieKey $OPSGENIE_API_KEY" \
  https://api.opsgenie.com/v2/heartbeats |
  jq -r '.data.heartbeats[] | [.name, .interval, .intervalUnit, .enabled, (.ownerTeam.name // "-"), .alertPriority] | @tsv'

On a migrated site, list each team's heartbeats with GET https://api.atlassian.com/jsm/ops/api/{cloudId}/v1/teams/{teamId}/heartbeats, which returns values and a links.next page link (Heartbeats API). Then find the sender of each name in crontabs, scheduler configs, and scripts: heartbeats/ URLs, lamp heartbeat calls, and the heartbeat's email address.

2. Create Each Monitor Before the Parallel Run

For each job, read its schedule and run time, then create the monitor before deploying the new check-in, with POST /applications/{id}/jobs on CronRadar's management API, sending the job's name, monitorKey, schedule, and gracePeriod (assistant access). The Hangfire and Quartz.NET 3.x integrations create monitors when they discover jobs, so they need no separate step. A monitor created in advance waits in pending, and if the first expected run plus grace passes without a check-in, CronRadar sends a never-executed alert, so a wiring mistake such as a missing key file shows up instead of staying silent. A monitor created by its first check-in can't catch that.

Choose channels and recipients in the application's Alerts tab. A channel test proves a destination receives messages; a fail followed by a successful run, from a harmless job in a separate test application, proves detection, delivery, and recovery (verification guide).

3. Send Both From the Same Job

This wrapper is adapted from the nightly backup in choosing a grace period, shown whole for copying, with the old Opsgenie ping added. It reports start, then complete or fail, to CronRadar, keeps the Opsgenie ping on success as before, and exits with the job's own code. Every request gives up after five seconds and ignores errors, so neither service can fail the backup. Both keys come from files only the job's account can read; the dead man's switch guide explains why not to set them in the crontab.

#!/bin/sh
# /opt/backup-monitored.sh
CRONRADAR_API_KEY=$(cat /etc/cronradar/api-key 2>/dev/null)
OPSGENIE_API_KEY=$(cat /etc/opsgenie/api-key 2>/dev/null)
url="https://cron.life/api/v1/ping/nightly-backup"
run_id="nightly-backup-$(date +%s)-$$"

report() {
  event=$1
  shift
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    --request POST --get --user "$CRONRADAR_API_KEY:" \
    --data-urlencode "schedule=30 2 * * *" \
    --data-urlencode "gracePeriod=900" \
    --data-urlencode "run_id=$run_id" \
    "$@" "$url/$event" || true
}

report start
/opt/backup.sh
rc=$?
if [ "$rc" -eq 0 ]; then
  report complete
  # The old heartbeat, kept for the parallel run (EU accounts: api.eu.opsgenie.com).
  # Delete this request at cutover.
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    --request POST --header "Authorization: GenieKey $OPSGENIE_API_KEY" \
    "https://api.opsgenie.com/v2/heartbeats/nightly-backup/ping" || true
else
  report fail --data-urlencode "message=backup.sh exited with code $rc"
fi
exit "$rc"

30 2 * * * /opt/backup-monitored.sh

For a heartbeat already in Jira Service Management, swap the Opsgenie request for the Jira Service Management ping shown earlier. The check-ins carry the schedule, so a deleted monitor is recreated by the next run.

No CronRadar SDK is installable for Node.js, Python, Celery, PHP, or Laravel (checked September 20, 2026). Jobs there report with HTTP check-ins, which don't discover jobs automatically; Node.js cron monitoring and Celery beat have check-in helpers. On .NET, the published CronRadar 1.0.13 wraps a job, and CronRadar.Hangfire 0.1.0 and CronRadar.Quartz 0.1.0 (for Quartz.NET 3.x) discover recurring jobs; Dead Man's Snitch vs CronRadar shows the setup and the Hangfire release's retry caveat.

4. Overlap for the Job's Longest Gap

Run both for at least one normal schedule window, and don't change the scheduler in the same deployment (migration guide). Make the window cover the job's longest gap, a weekend for a weekday job and a full month for a monthly one, and confirm each scheduled run reached CronRadar with a result, not just a start.

5. Disable, Then Remove the Ping, Then Delete

A heartbeat whose ping is removed expires one interval later and alerts. Disable it first with POST https://api.opsgenie.com/v2/heartbeats/:heartbeatName/disable, deploy the wrapper without the old request, and then delete it with DELETE https://api.opsgenie.com/v2/heartbeats/:heartbeatName (Heartbeat API). In Jira Service Management, send "enabled": false in a PATCH to /v1/teams/{teamId}/heartbeats?name={name}, and delete with a DELETE to the same URL (Heartbeats API).

6. Finish Before April 5, 2027

For the heartbeats you keep in Jira Service Management, confirm the team-based configuration was activated in Opsgenie under Settings > General > Heartbeat Configuration > Activate Heartbeat (feature changes). Then work through the Jira Service Management changes for each one: recreate it if it was v1, move its sender to the new email address or endpoint, and put an Atlassian API token on the host that pings.

Frequently Asked Questions

When does Opsgenie shut down?

Atlassian ended sales on June 4, 2025 and ends support on April 5, 2027. On that date, access is shut off and data that hasn't been migrated is deleted. Renewals after the end of sale are allowed only for terms that end before April 5, 2027.

Do Opsgenie heartbeats migrate to Jira Service Management?

Yes, they move automatically, but heartbeat monitoring works only on Jira Service Management Premium and Enterprise, not Free or Standard. Heartbeats on the old v1 version must be recreated by hand, email ping addresses change from opsgenie.net to atlassian.net, and API pings move to a team-scoped endpoint that authenticates with an Atlassian account's email and API token.

How do I convert an Opsgenie heartbeat interval to a cron schedule?

Take the schedule from the job, not the interval, and write it as five-field cron in UTC. Size the grace from the job's start delay plus, for a completion-only check-in, its run time. For a heartbeat sent when the job finishes, on a job with a fixed period and a steady run time, a grace of the interval minus the period plus the run time reproduces Opsgenie's alert time, but a grace sized from the job is usually shorter.

Why didn't my Opsgenie heartbeat alert when a run was skipped?

A heartbeat alerts only when the time since the last ping is longer than the interval. A 73-hour interval on a weekday job is long enough that skipping a Tuesday, Wednesday, or Thursday run leaves no gap longer than the interval, and a 10-minute interval on a 5-minute job usually misses a single skipped run. A cron schedule gives each run its own deadline, so a single skipped run alerts.

Can CronRadar send alerts to Opsgenie or Jira Service Management?

No. CronRadar's alert channels are email, Slack, webhook, Discord, and PagerDuty. Jira Service Management's Webhook integration is outgoing, so it doesn't accept CronRadar's webhook, and no other route into Jira Service Management has been verified.

This guide covers schedule 1.2.2, the current release on PyPI (checked October 30, 2026). Source links point to the 1.2.2 tag. For APScheduler, see Python scheduler monitoring; for a script that system cron starts, see Python script cron jobs.

How run_pending Decides What Runs

Each job stores a next_run time. run_pending() collects the jobs whose next_run has arrived, sorts them by next_run, and calls each one in turn, waiting for it to return (run_pending, should_run). The library has no thread or timer of its own, and "out of the box it is not possible to run the schedule in the background" (background execution), so nothing runs between calls. The docs' loop looks like this:

import time

import schedule

from jobs.tasks import rotate_logs

schedule.every().hour.at(":15").do(rotate_logs)

while True:
    schedule.run_pending()
    time.sleep(1)

Three details of that loop decide when your jobs actually run:

• Missed runs collapse into one. The run_pending docstring calls it "intended behavior that run_pending() does not run missed jobs": a job due every minute, checked once an hour, runs once, not 60 times.
• Interval jobs count from the end of the last run. Job.run() calls your function, then computes the next run from the current time (Job.run, _schedule_next_run). every(10).minutes first runs ten minutes after the job is registered, and a job that takes three minutes then runs about every 13 minutes. The docs say so in bold: "Schedule does not account for the time it takes for the job function to execute" (index).
• .at() jobs are anchored to the clock. every().day.at("02:00") runs at 02:00 each day however long the last run took.

.at() takes a format that depends on the unit, and if the format or unit doesn't fit, it raises ScheduleValueError as soon as it's called, before .do() registers the job (at, do):

One Exception Stops the Loop

"Schedule doesn't catch exceptions that happen during job execution. Therefore any exceptions thrown during job execution will bubble up and interrupt schedule's run_xyz function" (exception handling). In the loop above, the exception leaves while True, the process exits with a traceback, and every other job stops with it.

Wrapping schedule.run_pending() itself in try/except is worse. The exception leaves Job.run() before it records the run and computes the next one (lines 691-693), so the failed job stays due. On the next pass, a second later, it sorts first because its next_run is the oldest, runs again, and raises again, and the jobs sorted after it never get their turn. While it keeps failing, an hourly job becomes a once-a-second job that blocks every other job.

Catch the exception inside the job instead, as the docs recommend. This is their catch_exceptions decorator with logging instead of print and except Exception instead of a bare except, so Ctrl-C and sys.exit() still stop the process (KeyboardInterrupt and SystemExit inherit from BaseException, not Exception):

# jobs/runner.py
import functools
import logging

import schedule

log = logging.getLogger("jobs")


def catch_exceptions(cancel_on_failure=False):
    def decorator(job_func):
        @functools.wraps(job_func)
        def wrapper(*args, **kwargs):
            try:
                return job_func(*args, **kwargs)
            except Exception:
                log.exception("Scheduled job %s failed", job_func.__name__)
                if cancel_on_failure:
                    return schedule.CancelJob
        return wrapper
    return decorator

The wrapped job returns normally after a failure, so Job.run() schedules its next normal run and the loop moves on. With cancel_on_failure=True, the scheduler removes the job when it returns CancelJob (_run_job), so one failure ends that job until the process restarts.

Jobs Run One at a Time

"By default, schedule executes all jobs serially" (parallel execution). While one job runs, run_pending() doesn't return and nothing else is checked. If a report due at 01:30 takes 40 minutes, a backup set for .at("02:00") starts no earlier than 02:10, and an every(5).minutes job that came due in between runs once, not eight times.

Run Long Jobs in Threads

The docs' workaround starts each run in its own thread:

import threading

import schedule

from jobs.tasks import sync_inventory


def run_threaded(job_func):
    job_thread = threading.Thread(target=job_func)
    job_thread.start()


schedule.every(10).minutes.do(run_threaded, sync_inventory)

That changes four things, all of which follow from the scheduler only seeing run_threaded return:

• The loop stays on time. run_pending() returns as soon as the thread starts, so other jobs run when they're due, and an interval job's next run counts from when its thread started.
• An exception ends only its thread. Python passes it to threading.excepthook, which prints the traceback to stderr by default, and the loop keeps going. Keep catch_exceptions for a proper log line.
• CancelJob stops working. The scheduler sees run_threaded's return value, None, not your job's.
• Runs can overlap. A new thread starts every ten minutes whether or not the last one finished.

When a job must not overlap itself, skip the new run while the previous one holds a lock. Lock.acquire(blocking=False) returns False immediately instead of waiting:

# jobs/runner.py, continued
import threading


def run_threaded_once(job_func):
    """Start each run in a new thread, skipping it while the previous run is active."""
    lock = threading.Lock()

    def start():
        if not lock.acquire(blocking=False):
            log.warning("%s is still running; skipping this run", job_func.__name__)
            return

        def target():
            try:
                job_func()
            finally:
                lock.release()

        threading.Thread(target=target, name=job_func.__name__).start()

    return start

To cap the number of threads instead, the docs' second example puts jobs on a queue.Queue that one or more worker threads drain (parallel execution). To run the loop itself in a background thread of an existing application, see background execution. Either way, each Python process has its own default_scheduler (line 837), and nothing coordinates them, so a web app that starts the loop in each of four worker processes runs every job four times. Run the scheduler in one dedicated process; cron job running twice covers the other ways a job gets doubled.

A Restart Forgets Every Job

Jobs live in a plain list in memory (Scheduler.__init__), and .do() computes each job's first run from the moment it's called (do). The docs list "Job persistence (remember schedule between restarts)" first among the reasons not to use schedule (index). After a crash, deploy, or reboot:

• An .at() job skips the run it missed. A process that's down at 02:00 comes back with tomorrow's 02:00 as the next run, and today's never happens.
• An interval job starts its interval over. every(6).hours first runs six hours after the restart. A service deployed every four hours never runs it at all.
• Nothing catches up. There's no option to replay missed runs; run_all() runs every job immediately, whether or not it was due (run_all).

If a missed run must happen after an outage, the job has to remember its own last success somewhere durable and decide at startup. Missed runs after downtime compares how other schedulers handle this.

Time Zones and DST in .at()

Without a time zone, .at() uses the host's local time: the next run is computed from the naive datetime.datetime.now() (line 717). The same code runs at 02:00 UTC in a container set to UTC and at 02:00 Berlin time on a laptop set to Berlin. The docs add that jobs without a time zone "do not take clock-changes into account", so "a job that is set to run every 4 hours might execute after 3 realtime hours when DST goes into effect" (time zones).

.at() accepts a time zone as its second argument, as a string or a pytz time zone object:

schedule.every().day.at("02:00", "UTC").do(backup)
schedule.every().day.at("06:00", "America/New_York").do(send_digest)

• Zones need pytz, an optional extra. schedule has no required dependencies and lists pytz under its timezone extra (pyproject.toml), so a plain pip install schedule doesn't install it; use pip install "schedule[timezone]" or pip install pytz. .at() imports pytz only when you pass a zone (lines 498-508), and without it that .at() call raises ModuleNotFoundError: No module named 'pytz' (FAQ).
• Only .at() takes a zone. next_run and last_run are stored as naive times in the process's local zone either way (time zones).
• DST is handled when a zone is given. For .at("02:30", "Europe/Berlin"), on the night the clock skips from 02:00 to 03:00 the job runs once at 03:30; on the night 02:30 happens twice, it runs only the first time (time zones).
• Use 1.2.2 if you pass a zone. Zones arrived in 1.2.0; 1.2.1 fixed "schedule was off when using .at with timezone", and 1.2.2 fixed more cross-timezone bugs (HISTORY).

.at("02:00", "UTC") runs at the same instant on any host and matches a UTC cron schedule exactly. Cron timezone covers when a local zone is really what you want.

Keep the Process Alive With a Supervisor

The loop is the scheduler. If the process exits, from an uncaught exception, an out-of-memory kill, or a reboot, nothing runs and nothing logs that it didn't. Run it as a service that restarts it. With systemd:

# /etc/systemd/system/jobs.service
[Unit]
Description=Scheduled jobs (schedule library)
Wants=network-online.target
After=network-online.target

[Service]
User=jobs
WorkingDirectory=/srv/jobs
EnvironmentFile=/etc/jobs/jobs.env
ExecStart=/srv/jobs/.venv/bin/python -u -m jobs.scheduler
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target

Restart=always restarts the service "regardless of whether it exited cleanly or not"; the default is no (systemd.service). EnvironmentFile= reads variables such as CRONRADAR_API_KEY from a file (systemd.exec), which keeps the key out of the unit and the repository; make that file readable only by root. -u unbuffers stdout for any print() output from your jobs; Python script cron jobs explains the buffering. Cron @reboot covers network-online.target, the start limit, and OnFailure= for the same kind of service.

On stop or restart, systemd sends SIGTERM, then SIGKILL if the process is still there after a timeout (systemd.service). Python installs default handlers only for SIGPIPE and SIGINT (signal), so SIGTERM ends the process, cutting off whatever job is running. Python script cron jobs shows how to turn SIGTERM into a clean exit. A supervisor brings the loop back, but because of the restart behavior above, it doesn't bring back the run that was due while the process was down.

Report Each Run With an HTTP Check-In

None of the failures above alerts anyone: a dead loop leaves at most a traceback in the journal, and a run skipped after a restart or a job blocked behind a long one leaves nothing at all. A check-in from each run turns that silence into an alert from outside the process.

There's no installable CronRadar SDK for Python today; the Python integration docs list Python SDK connections as temporarily unavailable. Each job reports over HTTP, and HTTP check-ins don't discover jobs automatically: nothing reads schedule.get_jobs(), so give each job its own monitor key and a real schedule. This standard-library helper sends start, then complete or fail, with Basic authentication, a five-second timeout, and one run_id for both events. It logs monitoring errors instead of raising them and re-raises the job's own exception:

# jobs/cronradar.py
import base64
import functools
import logging
import os
import urllib.parse
import urllib.request
import uuid

log = logging.getLogger(__name__)


def _check_in(monitor_key, event, params):
    query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
    key = urllib.parse.quote(monitor_key, safe="")
    url = f"https://cron.life/api/v1/ping/{key}/{event}?{query}"
    try:
        token = base64.b64encode(f"{os.environ['CRONRADAR_API_KEY']}:".encode()).decode()
        request = urllib.request.Request(url, data=b"", method="POST")
        # Unlike add_header(), this header is not copied to a redirect.
        request.add_unredirected_header("Authorization", f"Basic {token}")
        with urllib.request.urlopen(request, timeout=5):
            pass
    except Exception as error:
        # A monitoring problem must never fail the job or change its result.
        log.warning("CronRadar %s for %s not recorded (%s)", event, monitor_key, type(error).__name__)


def reported(monitor_key, cron_schedule, grace_period=None):
    """Report start, then complete or fail, for each run. Re-raises the job's exception."""
    def decorator(job_func):
        @functools.wraps(job_func)
        def wrapper(*args, **kwargs):
            params = {"schedule": cron_schedule, "run_id": uuid.uuid4().hex}
            if grace_period is not None:
                params["gracePeriod"] = grace_period
            _check_in(monitor_key, "start", params)
            try:
                result = job_func(*args, **kwargs)
            except Exception as error:
                # The exception type only: never arguments, payloads, or messages.
                _check_in(monitor_key, "fail", {**params, "message": type(error).__name__})
                raise
            _check_in(monitor_key, "complete", params)
            return result
        return wrapper
    return decorator

The scheduler module combines the three pieces. reported sits innermost so it sees the exception; catch_exceptions logs it with a traceback through logging instead of leaving it to threading.excepthook's stderr print; run_threaded_once keeps a long backup from holding up the sync. The sync runs on the hour's ten-minute marks instead of every(10).minutes, so it matches */10 * * * * instead of drifting away from it:

# jobs/scheduler.py
import logging
import time

import schedule

from jobs.cronradar import reported
from jobs.runner import catch_exceptions, run_threaded_once
from jobs.tasks import backup_database, sync_inventory

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")


def monitored(job_func, monitor_key, cron_schedule, grace_period):
    """Report each run, log its exception, and run it in its own thread."""
    reported_job = reported(monitor_key, cron_schedule, grace_period)(job_func)
    return run_threaded_once(catch_exceptions()(reported_job))


backup = monitored(backup_database, "nightly-backup", "0 2 * * *", grace_period=600)
schedule.every().day.at("02:00", "UTC").do(backup)

sync = monitored(sync_inventory, "inventory-sync", "*/10 * * * *", grace_period=300)
for minute in range(0, 60, 10):
    schedule.every().hour.at(f":{minute:02d}").do(sync)

if __name__ == "__main__":
    while True:
        schedule.run_pending()
        time.sleep(1)

The six sync jobs share one sync callable, so they share one lock. The first check-in with a schedule creates the monitor, and sending it on every check-in recreates a deleted one on the next run (HTTP API). schedule and gracePeriod apply only when a check-in creates the monitor; change them later in its settings.

What CronRadar Sees for Each Failure

Alerts go to email, Slack, webhook, Discord, or PagerDuty. For the last row, scheduled job silent success shows how to send counts with complete, so an empty run is recorded as an outcome failure (outcomefailed) and opens an incident.

Translate Each Job to a UTC Cron Schedule

CronRadar reads schedule as standard five-field cron evaluated in UTC (schedule syntax), and after each check-in it expects the next run at the first cron time following the latest scheduled time at or before that check-in. A job that runs on the schedule's marks fits with a short grace period; one that drifts needs a long one.

The New York row follows CronRadar's daylight-saving rule: send the earlier of the two UTC times, 10:00 during daylight time, with a grace period of at least an hour plus the run's duration. In winter the job runs at 11:00 UTC, and the monitor shows warning each day from 10:00 until that run completes. For how grace periods interact with run time, see cron grace period.

Frequently Asked Questions

Why did my schedule loop stop running jobs?

Most often a job raised an exception, which schedule doesn't catch: it escapes run_pending() and ends the while True loop. Wrap each job in a decorator that catches and logs exceptions, as the exception handling docs show, and run the process under a supervisor such as systemd with Restart=always.

Does the schedule library run missed jobs after a restart?

No. Jobs exist only in memory, and each job's first run is computed when .do() is called, so a run that was due while the process was down never happens. An .at() job waits for its next time; an interval job waits a full interval from the restart.

How do I run schedule jobs in parallel?

Start each run in its own thread, as the parallel execution docs show, or put jobs on a queue that worker threads drain. Threaded runs can overlap, so use a lock when a job must not run twice at once.

How do I set a time zone in Python schedule?

Pass it as the second argument to .at(), such as every().day.at("02:00", "Europe/Berlin"). It requires pytz, which a plain pip install schedule doesn't install; use pip install "schedule[timezone]". Zones are available only in .at(). Without a zone, .at() uses the host's local time.

Is there a CronRadar SDK for the schedule library?

No. Python SDK connections are temporarily unavailable, so each job reports with an HTTP check-in, and nothing discovers schedule jobs automatically. Give each job its own monitor key and a UTC cron schedule that matches when it runs.

This guide covers Quartz.NET 3.22.9, the current 3.x release on NuGet (checked October 30, 2026). Every parsing rule below is from CronExpression.cs at that tag. Quartz.NET 4.x is also on NuGet (4.6.2, checked October 30, 2026); the daylight saving section notes where 4.x behaves differently, and CronRadar.Quartz 0.1.0 targets 3.x. For cron syntax in general, see cron expression syntax. For the same reference on Hangfire, see Hangfire cron expressions.

The Seven Fields, Seconds First

┌───────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌───────────── hour (0-23)
│ │ │ ┌───────────── day of month (1-31; also ? L W)
│ │ │ │ ┌───────────── month (1-12 or JAN-DEC)
│ │ │ │ │ ┌───────────── day of week (1-7 or SUN-SAT; 1 is Sunday; also ? L #)
│ │ │ │ │ │ ┌───────────── year (optional)
│ │ │ │ │ │ │
0 30 2 * * ? *

The class documentation lists "6 required fields and one optional field". Points from the source that catch people coming from Unix cron:

• Seconds come first. A five-field Unix expression such as 30 2 * * * fills only five fields, and the parser throws Unexpected end of expression.. More than seven fields throws Invalid expression has too many terms: followed by the expression.
• Day of week runs 1 to 7, with 1 as Sunday. In Unix cron and CronRadar, Sunday is 0 and Monday is 1. Names avoid the off-by-one: MON-FRI means the same thing in both.
• Steps start from a value. 0/15 in the minute field means 0, 15, 30, and 45, and * before / is the same as starting at 0. The docs warn that 7/6 in the month field "only turns on month 7, it does NOT mean every 6th month".
• Names and special characters aren't case-sensitive, and wrapping ranges such as 22-2 or NOV-FEB are supported.
• The year field defaults to every year when you leave it out. The parser fills it with *. The class documentation gives its range as 1970 to 2199, but 3.22.9 returns no fire time after MaxYear, the current year plus 100, so in 2026 a year after 2126 never fires.

Quartz.NET 3.22.9 also accepts H (hash) tokens, which CronScheduleBuilder.cs resolves from the trigger's identity. They don't exist in five-field cron, so they are out of scope here.

Why One Day Field Must Be ?

? means "no specific value" and is allowed only in the day-of-month and day-of-week fields. After reading the fields, BuildExpression checks that exactly one of them is ?. If neither is, or both are, it throws:

Support for specifying both a day-of-week AND a day-of-month parameter is not implemented.

That rules out the most common conversion mistake. 0 0 2 * * *, a six-field version of 0 2 * * *, restricts neither day field with ? and fails, and so does 0 0 2 ? * ?. Put ? in the field you aren't using:

Because Quartz never restricts both day fields at once, it has no equivalent of Unix cron's "either day matches" rule, or of the "both must match" rule that Cronos and CronRadar use. "Friday the 13th" can't be written as one Quartz expression.

Two more day-of-week checks throw before that: L combined with a list (Support for specifying 'L' with other days of the week is not implemented), and more than one # (Support for specifying multiple "nth" days is not implemented.).

L, W, LW, L-n, and #

The rules, from the class documentation and the parser:

• L means something different in each day field. In day of month it is the last day: 31 in January, 28 in February in a non-leap year. In day of week, by itself it is just Saturday; after a day number, 6L is the last Friday. The docs warn against combining L with lists or ranges, "as you'll get confusing/unexpected results".
• L-n counts back from the last day. The offset must be 30 or less, or the parser throws Offset from last day must be <= 30. 3.22.9 also parses L-nW and LW-n.
• W moves to the nearest weekday but stays in the month. If the 15th is a Saturday, 15W fires Friday the 14th; if it is a Sunday, Monday the 16th. 1W on a Saturday the 1st fires Monday the 3rd, because it won't jump back into the previous month. The class documentation says W works only on a single day, not a range or list, but the 3.22.9 parser tracks each nW entry separately, so a list such as 1W,15W parses and each entry shifts its own day.
• # takes 1 to 5. Anything else throws A numeric value between 1 and 5 must follow the '#' option. A fifth occurrence that doesn't exist that month means "no firing will occur that month", and only one # is allowed in the field: 3#1,6#3 is invalid.

For the five-field workaround for last-day schedules, see running cron on the last day of the month.

Common Schedules as Quartz Strings

0 9 1-7 * 1 means the first Monday only to a parser that requires both day fields to match, which CronRadar does (schedules). Linux cron runs it on the 1st through the 7th and on every Monday.

CronScheduleBuilder Helpers and the Strings They Build

The helpers in CronScheduleBuilder.cs build a string with CronExpressionBuilder, which renders an unset day of month as ?, an unset day of week as ? when a day of month is set and * otherwise, and day-of-week values as SUN through SAT:

CronScheduleBuilder.CronSchedule(string) validates the expression as soon as you call it, through CronExpression.ValidateExpression, which constructs a CronExpression. A bad string throws FormatException with one of the messages above while you build the trigger, not at fire time. The helpers check their arguments first and throw ArgumentException for an hour, minute, or day out of range.

Set the Time Zone With InTimeZone

A cron trigger whose time zone was never set reports TimeZoneInfo.Local (CronTriggerImpl.cs); why a Quartz.NET job is not firing covers debugging a trigger that runs at the host's local time. InTimeZone sets the zone on the builder's CronExpression, and Build() copies it onto the trigger:

using Quartz;

IJobDetail job = JobBuilder.Create<NightlyReportJob>()
    .WithIdentity("nightly-report", "reports")
    .Build();

// 02:30 UTC every day, whatever the host's zone.
ITrigger utcTrigger = TriggerBuilder.Create()
    .WithIdentity("nightly-report-utc", "reports")
    .ForJob(job)
    .WithSchedule(CronScheduleBuilder
        .CronSchedule("0 30 2 * * ?")
        .InTimeZone(TimeZoneInfo.Utc))
    .Build();

// 09:00 New York time on weekdays, following daylight saving time.
ITrigger localTrigger = TriggerBuilder.Create()
    .WithIdentity("weekday-digest-ny", "reports")
    .ForJob(job)
    .WithSchedule(CronScheduleBuilder
        .CronSchedule("0 0 9 ? * MON-FRI")
        .InTimeZone(TimeZoneInfo.FindSystemTimeZoneById("America/New_York")))
    .Build();

The zone ID has to resolve on every host that runs the scheduler; the Hangfire guide has a table of which .NET runtimes resolve IANA and Windows IDs. Missed fire times, including the ones a restart causes, are handled by the misfire instruction rather than the expression: see Quartz.NET misfire instructions.

Daylight Saving Time in Quartz.NET 3.x

The FAQ says a cron trigger "is never skipped by a transition, and never fires twice for one scheduled occurrence", and splits expressions into two kinds. A fixed-time expression has plain values or lists in the second, minute, and hour fields, such as 0 15 2 * * ?. An interval expression has a wildcard, step, or range in one of them.

For 0 30 2 * * ? in America/New_York, clocks jump from 02:00 EST to 03:00 EDT on March 14, 2027. Quartz 3.x fires at 02:30 EST (07:30 UTC) on March 13, at 03:30 EDT (07:30 UTC) on March 14, and at 02:30 EDT (06:30 UTC) on March 15. The local run time is fixed and the UTC time moves, which is what anything watching in UTC sees. Cron and daylight saving time covers the general problem.

Translating a Quartz Expression to Five-Field UTC

CronRadar reads schedules as standard five-field cron evaluated in UTC. Its schedule docs reject a seconds field, a year field, ?, L, W, #, shortcuts such as @daily, and 7 for Sunday. To rewrite a Quartz expression:

1. Drop the seconds field. It must be a single value. A step or list there, such as 0/30, runs more than once a minute and has no five-field equivalent.
2. Drop the year field. A restricted year has no equivalent.
3. Replace ? with *.
4. Fix day-of-week numbers. Subtract 1 (Quartz 2-6 is 1-5), or keep the names.
5. Rewrite L, W, LW, L-n, and #. There is no five-field form. Schedule the job on every candidate date, such as 28-31 for the last day, and let the job decide whether to do the work, checking in on every run, including the ones that exit early. 2#1 can become 1-7 in day of month with 1 in day of week, but only for a parser that matches both fields.
6. Convert the hours to UTC. With InTimeZone(TimeZoneInfo.Utc) there is nothing to do. For a zone with daylight saving time, the schedule docs say to use the earlier of the two UTC times and a grace period of at least an hour plus the job's usual duration: for 02:30 New York, 30 6 * * * with at least 3,600 seconds of grace.

Minute and hour steps carry over unchanged: CronRadar accepts 0/5 as well as */5.

On CronRadar.Quartz 0.1.0, make that translation yourself. The published package sends a cron trigger's CronExpressionString unchanged, from both its startup reconciliation and its job listener's start signal (CronRadarQuartzSchedule.cs). Every Quartz cron expression has a seconds field, so CronRadar rejects that schedule: discovery sync lists the monitor in errors, and a check-in carrying it gets 400 INVALID_REQUEST with Invalid schedule format. The conversion described in the Quartz integration guide belongs to the pending 0.1.1 release. 0.1.0 has no schedule override: [CronRadar] sets only the monitor key (CronRadarAttribute.cs). Until 0.1.1 ships, mark a cron-triggered job [SkipMonitor], which keeps both the reconciliation and the job listener away from it, and report the job yourself with its five-field UTC schedule: through WrapAsync in the base CronRadar 1.0.13 SDK, which takes the schedule as its schedule argument (CronRadar.cs), or through HTTP check-ins with Basic auth. Simple triggers that repeat are converted to an approximate five-field schedule in 0.1.0 already.

Once the schedule is in place, CronRadar marks a job warning when its run is late and critical when the grace period passes without one or the run reports failed, and alerts by email, Slack, webhook, Discord, or PagerDuty. Quartz.NET monitoring covers what to watch beyond the schedule, and why a Quartz.NET job is not firing covers a trigger that parses but never runs.

Frequently Asked Questions

What cron format does Quartz.NET use?

Six required fields, seconds first: second, minute, hour, day of month, month, day of week, with an optional seventh field for the year. Day of week runs 1 to 7 with Sunday as 1, and exactly one day field must be ?.

Why does Quartz say "Support for specifying both a day-of-week AND a day-of-month parameter is not implemented"?

Neither day field is ?, or both are. Put ? in the field you aren't restricting: 0 0 2 * * ? for every day, 0 0 9 ? * MON-FRI for weekdays.

How do I run a Quartz.NET job every 5 minutes?

Use 0 0/5 * * * ?. The seconds field is 0, the minute step starts at :00, and day of week is ?. The five-field equivalent is */5 * * * *.

What time zone does a Quartz.NET cron trigger use?

TimeZoneInfo.Local unless you call InTimeZone on the CronScheduleBuilder. Set it explicitly, TimeZoneInfo.Utc for jobs that should stay evenly spaced, so the trigger means the same thing on every host.

Can a Quartz.NET expression with L, W, or # be monitored?

Not as written in standard five-field cron. Schedule the job on every candidate date, such as 0 0 23 28-31 * ? instead of 0 0 23 L * ?, have the job exit early on the other days, and report the five-field form, 0 23 28-31 * * for a trigger in UTC, with a check-in on every run, including the ones that exit early. CronRadar.Quartz 0.1.0 forwards the Quartz string unchanged, so send that schedule through the base CronRadar SDK or HTTP check-ins.

This guide covers Claude Code 2.1.314, the current release on npm (checked October 30, 2026), and Codex CLI 0.166.0, the current release on npm (checked October 30, 2026), plus anthropics/claude-code-action v1.0.265, which installs Claude Code 2.1.314 (run.ts). Jobs that call a model API directly, and the ways they fail with an HTTP 200, are in monitoring scheduled AI agent runs; having an agent add monitoring code to a repository is AI agent cron monitoring setup.

The Two CLIs Side by Side

Sources: Claude Code's headless mode and CLI reference; Codex's non-interactive mode guide and exec CLI definition. Each row is covered below.

Claude Code: claude -p

Authenticate Without a Browser

Use an API key from the Claude Console in ANTHROPIC_API_KEY. In non-interactive mode, Claude Code always uses the key when it's present, and the key outranks CLAUDE_CODE_OAUTH_TOKEN and a /login subscription; cloud provider credentials and an ANTHROPIC_AUTH_TOKEN for an LLM gateway rank above it (authentication precedence).

A subscription works too. claude setup-token runs the browser sign-in once and prints a one-year OAuth token for CLAUDE_CODE_OAUTH_TOKEN, on Pro, Max, Ultra, Team, or Enterprise plans (long-lived token). It's a weaker fit for scheduled work: --bare, the recommended mode for scripts, doesn't read it; it's tied to the subscription of whoever generated it, which is why Anthropic recommends an API key for any secret shared across repositories (set up for an organization); and advertised Pro, Max, and Ultra usage limits "assume ordinary, individual usage of Claude Code and the Agent SDK" (legal and compliance). If you use one anyway, put its renewal date on a calendar.

Start From a Known Configuration With --bare

Without --bare, claude -p loads what an interactive session would: hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md, from the working directory and ~/.claude. It runs the hooks in the project's .claude/settings.json and connects the servers in its .mcp.json "even in a folder you've never trusted", with no trust dialog (bare mode). On a schedule, that means a commit to the repository's Claude configuration changes what next week's run does.

--bare skips all of that. Claude gets the Bash, file read, and file edit tools, and anything else is passed explicitly: --append-system-prompt-file for instructions such as your CLAUDE.md, --settings for settings, --mcp-config for MCP servers. It reads no OAuth credentials or keychain entries, so it authenticates with ANTHROPIC_API_KEY or an apiKeyHelper. It also turns background tasks off. A normal -p run can stay open after Claude's last turn waiting for background work it started, up to 10 minutes of idle waiting by default (CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS), or until a background command it started exits or reaches its time limit (background tasks at exit). Anthropic calls --bare "the recommended mode for scripted and SDK calls" and says it will become the default for -p.

Two more settings keep runs repeatable:

• Pin the CLI. Native installs update themselves in the background. Install a fixed version with curl -fsSL https://claude.ai/install.sh | bash -s 2.1.314 and set DISABLE_AUTOUPDATER=1 in the job's environment (install a specific version, disable auto-updates).
• Pin the model. Aliases such as sonnet "point to the recommended version for your provider and update over time" (model aliases). Pass a full model name instead, as in the CLI reference's --model claude-sonnet-5.

Permissions for a Run Nobody Watches

Since 2.1.302, a claude -p run with no permission mode set starts in Manual mode (default). File reads in the working directories and a built-in set of read-only commands run; any call that needs approval is denied unless an allow rule, a hook, or --permission-prompt-tool approves it (non-interactive runs). Choose the mode on purpose:

Sources: common setups, dontAsk, how the classifier evaluates actions, unattended runs.

• Allowlist syntax. Bash(npm test *) matches npm test alone and any command that starts with npm test ; the space before * is part of the rule (wildcard patterns). A compound command such as npm test && curl ... runs only if every part is allowed (compound commands).
• Auto mode can fall back. When --permission-mode auto asks for auto mode but it isn't available, because a settings file disables it, the model doesn't support it, or Anthropic has turned it off server-side, the session starts in Manual mode instead (which mode a session starts in). And after the classifier blocks an action 3 times in a row or 20 times in a session, a -p run doesn't stop: "the action doesn't run and Claude keeps working" (fallback). --permission-prompts none (2.1.259 and later) also tells Claude not to retry denied requests.
• bypassPermissions has no brakes. It "offers no protection against prompt injection or unintended actions", and Claude Code refuses it when running as root or under sudo on Linux and macOS (bypassPermissions).

In every mode, a denied call doesn't end the run, so a run can finish as success after some of its calls were denied. That's why the wrapper below counts denials.

Limit What the Agent Can Reach

Two settings narrow what Claude's shell commands can see:

• CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 removes credentials such as ANTHROPIC_API_KEY from the environments of the Bash commands, hooks, and stdio MCP servers Claude Code starts, while Claude Code keeps them for its own API calls. The docs describe it as reducing "what a prompt injection attack can read". It recognizes credentials by variable name or value shape and leaves GITHUB_TOKEN and GH_TOKEN in place (what the scrub removes).
• permissions.blockReadsOutsideWorkingDirectories. cat, head, grep, and the rest of the read-only command set run without approval in every mode, including on paths outside the repository (read-only commands). Setting this to true (2.1.257 and later) makes Claude's file tools refuse reads outside the working directories (setting) and makes recognized file-reading shell commands on those paths prompt in every mode (actions no mode auto-approves), which in a -p run with no one to answer means a denial.

Neither setting reaches a program that opens files itself. Claude Code's file rules cover its own tools and the file commands it recognizes in Bash, not "arbitrary subprocesses that read or write files indirectly, like a Python or Node script that opens files itself" (what Read and Edit rules cover), and an allowed npm test runs the test script from package.json (npm test), a file the agent can edit.

So keep the job's secrets file outside the checkout and hand each key only to the command that uses it, as the wrapper below does, but treat that as keeping keys out of the agent's environment, not out of its reach. The agent runs as the job's account, and a command it starts can read whatever that account can, including the secrets file, and use that account's Git credentials. To close that gap, run the agent CLI as a second account that can read neither.

Turn, Spend, and Time Limits

• --max-turns N limits agentic turns in print mode. There's no limit by default, and the run "exits with an error when the limit is reached" (CLI flags), with the result subtype error_max_turns.
• --max-budget-usd N stops the run once estimated spend reaches N, with the subtype error_max_budget_usd. The estimate is computed client-side and can differ from your bill, subagent spend counts toward it, and the response that crosses the cap still completes, so spend can pass the cap by up to that response's cost, plus whatever subagents still running at that moment spend before they stop (budget headroom).
• No wall-clock flag. Wrap the command in timeout. On SIGTERM, which timeout sends by default, Claude Code exits with code 143 and records no result for the turn in progress (SIGTERM); timeout itself exits 124 when the command times out, or 137 when the command or timeout receives KILL, which is what --kill-after sends to a command still running after TERM (GNU coreutils). Cron job timeouts covers choosing the limit.

Output and Exit Codes

Claude Code "exits with code 0 on success and a non-zero code when the run fails". An invalid flag is reported on stderr before the run starts; a failure inside the run, "such as missing authentication", is printed as the result on stdout (basic usage).

--output-format json prints the run's result as a JSON object with session metadata. These are the fields a scheduled job reads (handle the result, SDKResultMessage):

claude-code-action's rule, from run-claude-sdk.ts, is the one to copy: a run succeeded only if subtype is success and is_error is false, because, as its source comment puts it, a success subtype with is_error:true "means the run errored without producing a real result". For --json-schema, "if a run ends without valid structured output, for example because Claude declined the request, the response has no structured_output field", and a schema that isn't valid JSON Schema makes claude exit with Error: --json-schema is not a valid JSON Schema (structured output).

Codex CLI: codex exec

Authenticate With CODEX_API_KEY

codex exec reuses the CLI's saved login by default. For automation, OpenAI's guidance is to set CODEX_API_KEY "only for the Codex invocation that needs it", to make sure no untrusted code runs in the same process environment, and never to set OPENAI_API_KEY or CODEX_API_KEY as a job-level variable in a workflow that checks out or runs repository code (authenticate in automation):

CODEX_API_KEY="$CODEX_API_KEY" codex exec --json "triage open bug reports"

To store a key instead, pipe it in with printenv OPENAI_API_KEY | codex login --with-api-key (authentication); codex login status exits 0 when credentials are present, which makes a cheap preflight check (developer commands). With an API key, Codex uses standard API pricing instead of ChatGPT plan credits (authentication). Running CI as a ChatGPT account is documented as an advanced path: ~/.codex/auth.json holds access tokens, has to be refreshed in place and persisted between runs, and isn't meant for public or open-source repositories (authenticate in automation).

Pin the CLI with npm install -g @openai/codex@0.166.0; npm is one of the documented install methods (Codex CLI).

Sandbox and Approvals

• Read-only by default. codex exec runs in a read-only sandbox unless you pass --sandbox workspace-write, which lets it edit within the workspace. Use danger-full-access "only in a controlled environment", such as an isolated CI runner or container (permissions and safety).
• No network, no commits. In workspace-write, network access stays off unless sandbox_workspace_write.network_access is set (network access), and .git is protected as read-only (protected paths). Install dependencies before Codex starts, and commit from the wrapper.
• Nothing waits for approval. exec sets the approval policy to never unless your configuration selects automatic review (lib.rs), and it rejects any approval request that still arrives, with errors such as "command execution approval is not supported in exec mode" (lib.rs).
• Old and dangerous flags. --full-auto is no longer supported (permissions and safety). --approve-for-me routes approval requests through automatic review with the workspace-write sandbox, and --dangerously-bypass-approvals-and-sandbox (alias --yolo) is "EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed" (shared_options.rs).
• Ignore the host's configuration. --ignore-user-config skips $CODEX_HOME/config.toml (auth still uses CODEX_HOME), --ignore-rules skips user and project execpolicy .rules files, and --ephemeral writes no session files (cli.rs). With them, a run uses the flags you pass rather than whatever the host's config file says.
• Git repository required. Outside one, exec prints "Not inside a trusted directory and --skip-git-repo-check was not specified." and exits 1 (lib.rs). An enabled MCP server marked required = true that fails to initialize also makes codex exec exit with an error instead of continuing without it (permissions and safety).

Limits

codex exec 0.166.0 has no turn cap and no spend cap: neither its own options nor the shared ones define such a flag (cli.rs, shared_options.rs). Bound it with timeout, and watch spend through the token usage in its turn.completed event.

Output and Exit Codes

Codex streams progress to stderr and prints only the final agent message to stdout. With --json, stdout becomes JSON Lines, one event per line (machine-readable output). In 0.166.0 the events are thread.started, turn.started, turn.completed with token usage, turn.failed with an error, item.started, item.updated, item.completed, and error (exec_events.rs). Items include agent messages, file changes, and command executions with their exit_code and a status such as failed or declined (exec_events.rs). --output-schema <file> requests a final response that conforms to a JSON Schema, and -o/--output-last-message <file> writes the final message to a file.

exec exits 1 when the turn fails or is interrupted, or when Codex reports an error it won't retry; a turn that completes exits 0 (lib.rs), whatever the agent did or didn't change.

Exit 0 Doesn't Mean the Work Happened

The exit code separates the first three rows from the rest. For the others, ask the agent for a verdict in a fixed shape, then check it against what's on disk. One schema works for both CLIs, written the way Codex's own example writes them, with every field required and additionalProperties false:

{
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["done", "nothing_to_do", "blocked"] },
    "summary": { "type": "string" }
  },
  "required": ["status", "summary"],
  "additionalProperties": false
}

Claude Code takes it inline, as --json-schema "$(cat result-schema.json)"; Codex takes the path. The prompt says what each status means:

Fix the ESLint warnings that `npm run lint` reports under src/. Don't change
behavior, public APIs, tests, or anything outside src/. Run `npm run lint` and
`npm test` before you finish.

End with status "done" if you changed files and both commands pass,
"nothing_to_do" if there were no warnings, or "blocked" if you couldn't finish,
plus a short summary.

Then the wrapper believes the verdict only when the working tree agrees. git status --porcelain --untracked-files=all prints one line per modified, staged, or untracked file (git-status), so done with zero lines, or nothing_to_do with some, is a failure. That catches the run scheduled job silent success warns about, one where every command exited 0 and nothing useful happened.

A Wrapper for cron and systemd Timers

There's no CronRadar SDK for shell scripts, and HTTP check-ins don't discover jobs automatically, so the wrapper reports each run itself: start, then complete with outcome values, or fail with a short message. Check-ins use HTTP Basic auth with the key as the username and an empty password, so the key stays out of URLs and the crontab.

#!/usr/bin/env bash
# /opt/agent-jobs/lint-fix.sh: run a coding agent unattended, check what it did,
# push its branch for review, and report the run to CronRadar.
set -u
umask 077
PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin

KEY=weekly-lint-fix
SCHEDULE='30 4 * * 1' # Mondays 04:30 UTC, the same time as the crontab line
GRACE=900
JOBS=/opt/agent-jobs
REPO=/srv/agent-jobs/webapp # a clone used only by this job
URL="https://cron.life/api/v1/ping/$KEY"
RUN_ID="$KEY-$(date +%s)-$$"

# ANTHROPIC_API_KEY=... and CRONRADAR_API_KEY=... lines; mode 0600, owned by the
# job's account. Sourced without exporting, so each key is in the environment of
# only the command it's passed to below.
. /etc/agent-jobs/secrets.env || exit 1

checkin() {
  event=$1
  shift
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    --request POST --get --user "$CRONRADAR_API_KEY:" \
    --data-urlencode "schedule=$SCHEDULE" --data-urlencode "gracePeriod=$GRACE" \
    --data-urlencode "run_id=$RUN_ID" "$@" "$URL/$event" || true
}

fail() {
  echo "$KEY: $1" >&2
  checkin fail --data-urlencode "message=$1"
  exit 1
}

run_agent() { # sets rc, status, and extra (this tool's outcome values)
  timeout --kill-after=60 45m env \
    ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
    CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 \
    DISABLE_AUTOUPDATER=1 \
    claude --bare -p "$(cat "$JOBS/lint-fix.md")" \
    --model claude-sonnet-5 \
    --output-format json \
    --json-schema "$(cat "$JOBS/result-schema.json")" \
    --permission-mode dontAsk \
    --allowedTools "Read,Edit,Bash(npm run lint *),Bash(npm test *)" \
    --settings '{"permissions":{"blockReadsOutsideWorkingDirectories":true}}' \
    --max-turns 40 \
    --max-budget-usd 5 \
    > "$work/result.json" 2> "$work/stderr.log"
  rc=$?
  read -r subtype is_error status denials turns cost <<< "$(jq -r '[.subtype, .is_error,
    (.structured_output.status // "none"), (.permission_denials | length), .num_turns,
    ((.total_cost_usd // 0) * 100 | floor)] | map(tostring) | join(" ")' \
    "$work/result.json" 2> /dev/null)"
  # Success means subtype "success" and is_error false, as claude-code-action checks.
  if [ "$rc" -eq 0 ] && { [ "$subtype" != success ] || [ "$is_error" != false ]; }; then
    rc=1
  fi
  extra="\"permission_denials\":${denials:-0},\"turns\":${turns:-0},\"cost_cents\":${cost:-0}"
}

checkin start
work="/var/log/agent-jobs/$RUN_ID" # this run's output, kept for debugging
mkdir -p "$work" || fail "cannot create $work"

cd "$REPO" || fail "cannot enter $REPO"
{ git fetch --quiet origin && git checkout --quiet --force --detach origin/main &&
  git clean -fdq; } || fail "could not reset the checkout to origin/main"
npm ci --silent || fail "npm ci failed" # dependencies come before the agent starts

run_agent
case $rc in
  0) ;;
  124) fail "agent stopped at the 45-minute limit" ;;
  137) fail "agent killed with KILL, by the 45-minute limit or another process" ;;
  *) fail "agent run failed with exit code $rc" ;;
esac
case $status in
  done | nothing_to_do | blocked) ;;
  *) fail "agent returned no valid verdict" ;;
esac

files_changed=$(($(git status --porcelain --untracked-files=all | wc -l)))
case "$status:$((files_changed > 0))" in
  done:0) fail "agent reported done but changed no files" ;;
  nothing_to_do:1) fail "agent reported nothing to do but changed files" ;;
esac

if [ "$status" = done ]; then
  branch="agent/$KEY-$(date -u +%Y%m%d)"
  { git switch --quiet --create "$branch" && git add --all; } ||
    fail "could not stage the changes on $branch"
  # Refuse to push changes that contain one of this job's keys as plain text.
  for secret in "${ANTHROPIC_API_KEY:-}" "${CODEX_API_KEY:-}" "$CRONRADAR_API_KEY"; do
    if [ -n "$secret" ] && git diff --cached --text | grep -qF -- "$secret"; then
      fail "the agent's changes contain an API key; nothing was pushed"
    fi
  done
  { git commit --quiet --message "Fix lint warnings (scheduled agent run)" &&
    git push --quiet origin "$branch"; } || fail "could not push $branch"
fi

blocked=false
[ "$status" != blocked ] || blocked=true
curl --fail --silent --show-error --max-time 5 --output /dev/null \
  --request POST --user "$CRONRADAR_API_KEY:" --header "Content-Type: application/json" \
  --data "{\"outcomes\":{\"files_changed\":$files_changed,\"blocked\":$blocked,$extra}}" \
  "$URL/complete?run_id=$RUN_ID" || true

For Codex, keep everything else, put CODEX_API_KEY=... in the secrets file, and replace run_agent:

run_agent() { # Codex CLI 0.166.0: same contract as the Claude Code version
  timeout --kill-after=60 45m env CODEX_API_KEY="$CODEX_API_KEY" \
    codex exec --json --ephemeral --ignore-user-config --ignore-rules \
    --sandbox workspace-write \
    --output-schema "$JOBS/result-schema.json" \
    --output-last-message "$work/final.json" \
    "$(cat "$JOBS/lint-fix.md")" \
    > "$work/events.jsonl" 2> "$work/stderr.log"
  rc=$?
  status=$(jq -r '.status' "$work/final.json" 2> /dev/null) || status=none
  tokens=$(jq -s '[.[] | select(.type == "turn.completed")] | last | .usage.output_tokens // 0' \
    "$work/events.jsonl" 2> /dev/null) || tokens=0
  extra="\"output_tokens\":$tokens"
}

Schedule it from the job account's crontab, on a host whose clock is UTC (cron time zones covers the alternatives):

30 4 * * 1 /opt/agent-jobs/lint-fix.sh >> /var/log/agent-jobs/lint-fix.log 2>&1

Or with a systemd timer. OnCalendar= accepts the literal zone UTC (systemd.time(7)), and because a Type=oneshot service has no start timeout by default (systemd.service(5)), TimeoutStartSec= is a backstop above the wrapper's own limit. systemd timers covers the rest of the options:

# /etc/systemd/system/weekly-lint-fix.service
[Service]
Type=oneshot
User=agentjobs
ExecStart=/opt/agent-jobs/lint-fix.sh
TimeoutStartSec=1h

# /etc/systemd/system/weekly-lint-fix.timer
[Timer]
OnCalendar=Mon *-*-* 04:30:00 UTC

[Install]
WantedBy=timers.target

What the wrapper does, and why:

• start comes first, so a broken checkout or a failed npm ci reports fail instead of looking like a missed run. A missing secrets file exits before any check-in, and CronRadar alerts on the run that never arrived: warning once it's late, critical once the grace period passes.
• The check-ins work as in GitHub Actions scheduled workflows: they can't break the job, the start carries the schedule so the first run creates the monitor, and a run that dies after start is flagged as stuck only once the next scheduled time plus grace passes, which for a weekly job is next Monday. CronRadar evaluates the schedule as five-field cron in UTC. The timeout turns a hung agent into a fail at 45 minutes, which opens an incident immediately.
• Keys stay out of the agent's environment, not out of its reach. ANTHROPIC_API_KEY is passed only to claude, and CRONRADAR_API_KEY only to the check-in requests, but the agent runs as the job's account, which can read the secrets file; the second account described above closes that.
• The verdict has to match the tree. A run that claims work it didn't do, or does work it didn't report, fails; a blocked run completes with blocked: true, which the outcome checks below turn into an incident.
• Only the wrapper pushes. The Claude Code allowlist names no git command, and Codex's workspace-write sandbox keeps .git read-only and the network off. The wrapper pushes only a done run, to a new branch, for a person to review, and refuses when the staged changes contain one of the job's keys as plain text. That check misses an encoded key, and the push credentials belong to the account the agent runs as, so the second account is the real boundary. For schedules frequent enough to overlap, add a lock as in preventing overlapping cron jobs.

A Scheduled GitHub Actions Workflow

With a prompt input, anthropics/claude-code-action runs in automation mode on any event, including schedule. Claude has no shell or GitHub API access until you grant tools, and results appear in the workflow run log (automation mode, run on a schedule). Three details matter for scheduled runs:

• The bot check applies. The action rejects a bot actor unless it's listed in allowed_bots, and GitHub attributes a scheduled run to a repository user, "usually the one who last changed the workflow's cron schedule". If a bot made that change, scheduled runs fail (who can trigger runs).
• Claude inherits the step's environment. The action builds Claude's environment from a copy of the whole process environment, minus the OIDC token request variables and the serialized action inputs (parse-sdk-options.ts). Give CRONRADAR_API_KEY to the report steps only, never at job level.
• The outputs say what happened. execution_file is the path of a JSON array of every message from the run, including the final result (action.yml, execution-file.ts). conclusion is success when the run succeeds; on a failed run the action fails the step without setting it, although action.yml describes it as success or failure (run.ts), so test for success, as the report step below does. With --json-schema in claude_args, a run that returns no structured output fails the step, and by default the log shows only a sanitized summary of the result (run-claude-sdk.ts); the show_full_output input warns that full output "may contain secrets" (action.yml).

To avoid storing an Anthropic key at all, the action can exchange the workflow's GitHub OIDC token through workload identity federation, with the anthropic_federation_rule_id and anthropic_organization_id inputs and id-token: write (set up for an organization). This workflow uses a repository secret:

# .github/workflows/daily-report.yml
name: Daily report

on:
  schedule:
    - cron: '17 9 * * *'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}

jobs:
  report:
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
      issues: read
      id-token: write
    defaults:
      run:
        shell: bash
    env:
      PING_URL: https://cron.life/api/v1/ping/daily-repo-report
      MONITOR_SCHEDULE: '17 9 * * *' # keep in step with on.schedule
      GRACE_SECONDS: '3600'
    steps:
      - name: Report start to CronRadar
        timeout-minutes: 1
        env:
          CRONRADAR_API_KEY: ${{ secrets.CRONRADAR_API_KEY }}
        run: |
          curl --fail --silent --show-error --max-time 5 --output /dev/null \
            --request POST --get --user "$CRONRADAR_API_KEY:" \
            --data-urlencode "schedule=$MONITOR_SCHEDULE" \
            --data-urlencode "gracePeriod=$GRACE_SECONDS" \
            --data-urlencode "run_id=$GITHUB_RUN_ID" \
            "$PING_URL/start" || true

      - name: Run Claude Code
        id: claude
        uses: anthropics/claude-code-action@6d5ae526d25ce88daa2200be073e1a373167f064 # v1.0.265
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Summarize yesterday's commits and the issues opened yesterday.
            End with status "done" and the summary, "nothing_to_do" if there
            were no commits or new issues, or "blocked" if you couldn't read them.
          claude_args: |
            --model claude-sonnet-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"
            --max-turns 20
            --max-budget-usd 2
            --json-schema '{"type":"object","properties":{"status":{"type":"string","enum":["done","nothing_to_do","blocked"]},"summary":{"type":"string"}},"required":["status","summary"],"additionalProperties":false}'

      - name: Report result to CronRadar
        if: always()
        timeout-minutes: 1
        env:
          CRONRADAR_API_KEY: ${{ secrets.CRONRADAR_API_KEY }}
          CONCLUSION: ${{ steps.claude.outputs.conclusion }}
          EXECUTION_FILE: ${{ steps.claude.outputs.execution_file }}
        run: |
          body=
          if [ "$CONCLUSION" = success ]; then
            body=$(jq -c '[.[] | select(.type == "result")] | last | {outcomes: {
              blocked: (.structured_output.status == "blocked"),
              permission_denials: (.permission_denials | length),
              turns: .num_turns,
              cost_cents: ((.total_cost_usd // 0) * 100 | floor)}}' "$EXECUTION_FILE") || body=
          fi
          if [ -n "$body" ]; then
            curl --fail --silent --show-error --max-time 5 --output /dev/null \
              --request POST --user "$CRONRADAR_API_KEY:" \
              --header "Content-Type: application/json" --data "$body" \
              "$PING_URL/complete?run_id=$GITHUB_RUN_ID" || true
          else
            curl --fail --silent --show-error --max-time 5 --output /dev/null \
              --request POST --get --user "$CRONRADAR_API_KEY:" \
              --data-urlencode "run_id=$GITHUB_RUN_ID" \
              --data-urlencode "message=Claude Code run did not succeed: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" \
              "$PING_URL/fail" || true
          fi

The allowed tools and the id-token permission follow Anthropic's own scheduled example, which reads commits and issues through two GitHub MCP tools, so it needs no checkout (run on a schedule). The action pin is the v1.0.265 commit, which also fixes the Claude Code version. jq is preinstalled on the ubuntu-24.04 image (runner image). The report step runs after a failure, a cancellation, or the job's timeout, and anything but a successful run reports fail. GitHub's own schedule can start runs late or drop them; GitHub Actions scheduled workflows covers that and why the grace here is an hour.

For Codex, OpenAI recommends openai/codex-action@v1 over installing and authenticating the CLI yourself (non-interactive mode). It starts a Responses API proxy for the key, runs codex exec, removes sudo before running Codex by default (safety-strategy: drop-sudo), takes extra flags such as --output-schema through codex-args, and returns the last message in its final-message output (Codex GitHub Action). The same start and result steps fit around it, with the verdict read from final-message instead of the execution file.

Outcome Checks That Catch Quiet Runs

Set expectations on the reported values under the monitor's Outcome checks, and a complete that misses one marks the run outcome-failed and opens an incident; scheduled job silent success covers the rules for expectations and the complete body. For the two jobs above:

For the daily report, use turns <= 15 and cost_cents <= 100 under its caps of 20 turns and $2; for the Codex variant, put a ceiling on output_tokens taken from your own runs. Take thresholds from a few weeks of history rather than guessing (choosing thresholds).

CronRadar rejects a body it can't accept, such as a sixth value or a string, with a 400 and records no completion, and since the next start still arrives on schedule, that can go unnoticed. Send one completion by hand with curl --fail-with-body before relying on it. CronRadar also rejects a fail message longer than 1,000 characters with a 400 and records no failure. Keep prompts, summaries, and diffs out of check-ins, as monitoring scheduled AI agent runs explains. Alerts go to email, Slack, a webhook, Discord, or PagerDuty.

Frequently Asked Questions

How do I run Claude Code from a cron job?

Call claude --bare -p from a wrapper script that loads ANTHROPIC_API_KEY from a file readable only by the job's account, sets --permission-mode dontAsk with an --allowedTools list, caps the run with --max-turns and --max-budget-usd, and wraps it in timeout. Use --output-format json and check that subtype is success and is_error is false, not just the exit code.

How does Claude Code authenticate without a browser?

With an API key in ANTHROPIC_API_KEY, which non-interactive runs always use when it's set. For a subscription, claude setup-token prints a one-year OAuth token for CLAUDE_CODE_OAUTH_TOKEN, but --bare doesn't read it and it's tied to one person's subscription, so an API key suits shared, scheduled jobs better.

How do I run Codex CLI non-interactively?

Use codex exec "<prompt>" inside a Git repository, with CODEX_API_KEY set only for that command. It runs read-only unless you pass --sandbox workspace-write, never waits for approvals, and exits 1 when its turn fails. Add --json for an event stream and --output-schema with -o for a final answer your script can parse.

How do I stop a scheduled agent run from running too long or costing too much?

Claude Code has --max-turns and --max-budget-usd; the budget is a client-side estimate that one response, plus any subagents still running, can overshoot, so leave headroom. Codex 0.166.0 has neither flag. For both, timeout bounds wall-clock time and exits 124 when it stops the agent, or 137 if it had to send KILL, and outcome checks on turns or cost alert well before the hard stop.

Why did my scheduled agent run exit 0 but change nothing?

The agent finished its turn without doing the work: its tool calls were denied, auto mode fell back or kept blocking, it decided there was nothing to do, or it described changes it never made. Have it return a verdict in a JSON schema, compare that with git status, and count permission_denials on Claude Code.

How do I get alerted when a scheduled agent run fails or does nothing?

Send a start check-in before the agent runs and complete or fail after, so a missed, failed, or hung run alerts. Attach counts such as files changed, denials, turns, and cost, plus a blocked flag, to the completion, and configure outcome checks on them, so a run that exits 0 without doing its job still opens an incident.

This guide covers UptimeRobot's hosted service and its v3 API, spec version 3.0 in the published OpenAPI file, as documented in its help center and on its pricing page (checked October 30, 2026). For why a job needs a heartbeat at all, see the dead man's switch guide; for what uptime checks miss, see cron monitoring vs uptime monitoring. The comparison at the end covers UptimeRobot's heartbeat feature only, not its uptime checks or status pages.

How a Heartbeat Monitor Decides a Job Is Down

Create the monitor with + Add New Monitor and the Heartbeat type, then set a Friendly Name, the interval, the grace period, and the alert contacts. UptimeRobot generates the monitor's unique URL when you create it (quick setup guide). The help center's examples use URLs of the form https://heartbeat.uptimerobot.com/m794yyyyyyyy-xxxxxxxxxxxxxxx (sending requests), and the API returns the URL as heartbeatUrl (openapi.yaml).

What the documentation says about requests and deadlines:

• Methods. UptimeRobot receives only GET and POST requests to the heartbeat URL (monitor status troubleshooting).
• The deadline. If a request doesn't arrive within the interval plus the grace period, the monitor goes down and you're alerted (cron job monitoring). The API describes the grace period as the time "to wait past the expected heartbeat before alerting" (openapi.yaml).
• A job that never reports. The quick setup guide says a heartbeat monitor that receives no request is marked down, so a job that was never installed is caught too.
• What it records. Up or down status, the time of the last heartbeat, uptime percentage, and incident history (cron job monitoring). Run duration isn't on that list.

The Request Carries No Result

The heartbeat documentation describes one kind of request: a GET or POST to the URL. It documents no parameter for reporting a failure, a start, or a message. A job therefore reports success by sending the request and failure by not sending it, and UptimeRobot learns of a failed run at the same moment it would learn of a run that never started: when the interval plus grace runs out. The alert can't say which of the two happened or include the job's exit code.

Interval and Grace Limits

An Interval, Not a Cron Schedule

The help center tells you to match the crontab entry to the monitor: replace the 5 in */5 "with your monitor's interval in minutes" (sending requests). The API's heartbeat create schema has interval and gracePeriod and no schedule field (openapi.yaml). Interval plus grace has to exceed the longest normal gap between two requests from the job, and any slack beyond that is time a missed run goes unreported. What that means for common schedules:

• Daily jobs: the period goes in the interval, the variation in the grace. A backup that starts at 03:00, takes 10 to 40 minutes, and sends the request when it finishes has gaps of up to 24 hours 30 minutes between requests. An interval of 1,440 minutes (24 hours) with a 45-minute grace leaves 15 minutes of headroom. On a host whose clock follows daylight saving time, the night the clocks go back adds an hour, so use a grace of 1 hour 45 minutes there. The Uptime Kuma guide works through the same arithmetic for a single interval, and the grace period guide shows how to derive the numbers from measured runs.
• Weekday-only and other irregular schedules need an interval that covers their longest gap, such as the weekend, which delays the alert for a run missed on any weekday; cron monitoring vs uptime monitoring works through the 0 6 * * 1-5 case.
• Monthly jobs on the 1st have gaps of up to 31 days, which is the maximum interval, so only the grace is left to cover run time and start delay.
• Quarterly and other jobs that run less often than monthly don't fit: a quarter's gap of roughly 90 days is longer than the 31-day maximum interval plus the 24-hour maximum grace, so the monitor would go down between every pair of runs.

Leave the notification delay at 0 on heartbeat monitors. It's added to interval plus grace on every alert, and the grace already absorbs normal variation.

Plans and Prices for Heartbeat Monitoring

The pricing page's feature comparison marks Heartbeat monitoring as not included on Free and included on Solo, Team, and Scale, and Enterprise includes everything in Scale (pricing, checked October 30, 2026). A heartbeat is one of the monitor types (quick setup guide), and each plan's limit counts every monitor on the account (downgrades), so heartbeats share the count with HTTP, keyword, ping, and other monitors.

Team and Scale prices changed between loads of the page on October 30, 2026: from the same US connection, some loads served the lower set of figures and others the higher, while Solo's prices were the same in every load. UptimeRobot's pricing.md says its anonymous pricing endpoint is geo-banded and asks for prices to be checked against the live page before they're quoted, so check the page before you choose a plan. The page's annual totals follow whichever set it serves: $144 a year for Solo with 10 monitors, $396 or $468 for Team, and $804 or $948 for Scale with 200, and the page says annual billing saves about 15%. The page's feature comparison also lists other plan differences that affect heartbeats:

• Notification channels. Email, SMS, voice call, Email2SMS, the mobile app, and Google Chat, Discord, Pushover, Pushbullet, and Splunk on every plan; Slack, Mattermost, Telegram, and Microsoft Teams from Solo; webhook, Zapier, and PagerDuty from Team. The mobile app is one of the personal channels, sending push notifications (notification channels). Solo includes 10 to 20 SMS or voice call credits, Team 30, and Scale 50 to 200, and credits don't renew with the plan.
• Recurring and delayed notifications, and maintenance windows, are on paid plans, so every plan that has heartbeats has them.
• Seats. The table lists no included login seats on Solo, 3 on Team, and 5 on Scale.
• Data retention. 12 months on Solo, 24 months on Team and Scale (data retention).

Notifications and Maintenance Windows

• Contacts are assigned per monitor. A contact that isn't assigned to a monitor gets no alerts from it; assign contacts one monitor at a time or with bulk actions. Each contact can receive Up and Down alerts, both on by default (notification channels).
• Delay and repeat are set per contact on each monitor, in minutes: the delay is how long to wait after a failure before alerting, and the repeat is how often the alert recurs (recurring notifications).
• Alert storm protection is a beta on paid plans and off by default. When the number of monitors that go down within a time window (5 minutes by default) reaches your threshold, it suppresses their individual Down notifications, sends one storm notification with the number of monitors affected and a link to the incidents, and cancels pending delayed and repeat notifications while the storm lasts (alert storm protection). With it on, a job that stops during a wider outage gets no Down notification of its own.
• Maintenance windows treat heartbeats differently. Most monitor types leave the window with the status they had going in. A heartbeat monitor that is already down when a window starts stays down for the whole window, even after its job resumes, and turns up only on the first check after the window ends; the help center's advice is to start the window before you stop the job. Windows follow the account's time zone, and checks run less often inside one (maintenance windows).

A Cron Wrapper That Sends the Heartbeat

Set up the monitor first:

1. Create a Heartbeat monitor named after the job, with the interval and grace from the sizing above, and assign at least one alert contact.
2. Save the heartbeat URL in a file owned by the job's account with mode 600, here /etc/uptimerobot/nightly-backup.url. The help center's examples put the URL in the crontab line and send nothing else with it, so the URL alone marks the job as having run. Keep it out of crontabs and repositories.

The wrapper runs the job and sends the heartbeat only when the job succeeds:

#!/bin/sh
# /opt/backup-uptimerobot.sh: run the backup, then send the UptimeRobot heartbeat if it succeeded.
# The file holds the monitor's heartbeat URL and is readable only by this account.
heartbeat_url=$(cat /etc/uptimerobot/nightly-backup.url 2>/dev/null)

/opt/backup.sh
rc=$?

if [ "$rc" -eq 0 ] && [ -n "$heartbeat_url" ]; then
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    "$heartbeat_url" || true
fi
exit "$rc"

Schedule it with 0 3 * * * /opt/backup-uptimerobot.sh. A request means success, so a non-zero exit sends nothing and the monitor goes down once interval plus grace pass. --max-time 5 caps the request, || true ignores a failed one, and the script exits with the backup's own code, so an unreachable UptimeRobot can't fail or stall the job; --show-error still writes a failed request to the job's stderr. The help center's curl example passes --insecure, which skips TLS certificate verification (curl manual); this wrapper leaves verification on. Cron shell script best practices covers keeping the job's exit code honest.

A hung run looks the same as a missed one: no request, then an alert when interval plus grace pass, while the hung process keeps running. To end a hung run at a time you choose, put a time limit around the job; cron job timeouts covers GNU timeout and its exit codes.

Creating Heartbeat Monitors Through the API

For many jobs, or an AI agent setting monitors up, the v3 API creates the same monitor. POST /v3/monitors with the heartbeat body requires friendlyName, type, and interval, takes gracePeriod optionally, both in seconds, and returns the monitor including heartbeatUrl; each entry in assignedAlertContacts needs alertContactId, threshold, and recurrence, and GET /v3/user/alert-contacts lists contacts with their id (openapi.yaml). Requests send an API key, created in the dashboard's API section (API help), as a bearer token (openapi.yaml).

# UPTIMEROBOT_API_KEY comes from your secret store.
# 12345 stands for an alert contact id returned by GET /v3/user/alert-contacts.
curl --fail-with-body --silent --show-error \
  --request POST "https://api.uptimerobot.com/v3/monitors" \
  --header "Authorization: Bearer $UPTIMEROBOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "friendlyName": "nightly-backup",
    "type": "HEARTBEAT",
    "interval": 86400,
    "gracePeriod": 2700,
    "assignedAlertContacts": [
      { "alertContactId": 12345, "threshold": 0, "recurrence": 1440 }
    ]
  }'

That is the daily backup from the sizing above: a 24-hour interval, a 45-minute grace, no notification delay, and a repeat every 1,440 minutes (24 hours). Save the returned heartbeatUrl in the job's URL file. Each job is still its own create call and its own URL to distribute; the URL exists only once the monitor does, so a job can't register itself with its first request.

UptimeRobot Heartbeats and CronRadar Compared

CronRadar is a hosted monitor for scheduled jobs only. UptimeRobot facts below were checked October 30, 2026.

What Each Costs by Job Count

Monthly list prices before tax, assuming the UptimeRobot account has no other monitors and every CronRadar job is in one schedule class. These compare job counts, not equivalent products: UptimeRobot's monitors can also be uptime checks, and CronRadar doesn't charge per seat.

Where a cell shows two UptimeRobot prices, the pricing page served both on October 30, 2026, as described in the plans section above. For daily or hourly jobs, CronRadar's list price is lower than UptimeRobot's on both billing periods up to 50 jobs. At 100 and 200 jobs it is lower only than UptimeRobot's higher monthly price: UptimeRobot's annual billing, and its lower monthly price, cost less. At 500, UptimeRobot is lower on both. For jobs every 5 to 59 minutes, UptimeRobot is lower from 50 jobs. Above 500 monitors UptimeRobot quotes Enterprise; CronRadar has no monitor limit.

The CronRadar figures are Grow list prices: the first 10 active monitors are free, fastest schedules first, and each further monitor costs $1 a month on a Frequent schedule (5 minutes to under an hour) or $0.50 on a Standard one (hourly or less often), billed in arrears on the month's peak (pricing).

The Same Backup Reporting to CronRadar

Shell scripts have no CronRadar SDK. The Node.js, Python, Celery, PHP, and Laravel SDKs are also unavailable, so those jobs report with HTTP check-ins too, and HTTP check-ins don't discover jobs automatically. The Uptime Kuma guide has the full CronRadar wrapper for this backup: it reads the API key from a file only the job's account can read, sends it with HTTP Basic auth as the username with an empty password, reports start before the backup and complete or fail after it, and keeps the same --max-time 5 and || true guards as the UptimeRobot wrapper above.

Two things differ from the UptimeRobot monitor. The failure is sent, with the exit code in its message, and alerts immediately instead of when interval plus grace run out. And the deadline follows the schedule rather than the last request, so the grace covers only the start: with schedule=0 3 * * * and gracePeriod=900, a missed run turns the monitor critical once 03:15 UTC passes, however long the previous run took, where the UptimeRobot monitor above needs a 45-minute grace to absorb the variation in the backup's run time. CronRadar reads the schedule in UTC; schedule syntax covers converting a local schedule and one difference from Linux cron when both day fields are restricted.

The same guide covers CronRadar's limits: stuck detection works per job rather than per run, and a monitor created by its first check-in can't flag a job that never runs unless you create it in the dashboard first. The .NET packages are the only installable SDKs (CronRadar 1.0.13, CronRadar.Hangfire 0.1.0, CronRadar.Quartz 0.1.0, checked September 20, 2026): CronRadar 1.0.13 can't send outcome values, and CronRadar.Hangfire 0.1.0 can report a failure before Hangfire finishes retrying. CronRadar has no SMS or voice call alerts, offers no contractual SLA, and publishes no availability figure.

When UptimeRobot Heartbeats Fit

• You already pay for UptimeRobot and your plan has spare monitors: heartbeats share the notifications and dashboard you use for uptime checks.
• Your jobs run on a fixed interval between 1 minute and 31 days, such as every 15 minutes or every hour, so the job's period can be the monitor's interval.
• You want SMS or voice call alerts for a missed job, which CronRadar doesn't offer.
• You run many jobs, where UptimeRobot's list price in the table above is lower: from 50 jobs on schedules every 5 to 59 minutes, from 100 daily or hourly jobs on annual billing or at the lower monthly price the page sometimes shows, and at 500 daily or hourly jobs on either billing.

When a Schedule-Aware Cron Monitor Fits

• Schedules an interval can't express: weekdays only, fixed times several times a day, or anything less frequent than monthly.
• Failures should alert when they happen, with the job's message, instead of when the interval runs out.
• You want start and finish signals, for stuck runs, checks on reported results, and run duration, which isn't among UptimeRobot's recorded heartbeat metrics.
• Monitors should appear from a job's first check-in or from Hangfire and Quartz.NET discovery rather than one form or API call per job.
• You need webhook or PagerDuty alerts for a handful of jobs without moving to Team.

Cron monitoring tools compared puts hosted options side by side.

Frequently Asked Questions

Does UptimeRobot monitor cron jobs?

Yes, with a Heartbeat monitor, which the product pages also call a cron job monitor. The job sends a GET or POST request to the monitor's URL, and UptimeRobot marks it down when no request arrives within the interval plus the grace period.

Is UptimeRobot heartbeat monitoring free?

No. The Free plan doesn't include heartbeat monitors. As of October 30, 2026, the cheapest plan with them is Solo: $13 a month billed monthly, or $12 a month billed annually, for 10 monitors of any type.

What is the longest interval for an UptimeRobot heartbeat monitor?

31 days, which the API expresses as 2,678,400 seconds, plus a grace period of up to 86,400 seconds. Jobs with longer gaps between runs, such as quarterly ones, don't fit in one heartbeat monitor.

Can a cron job report a failure to UptimeRobot?

Not through the documented heartbeat request, which is a GET or POST to the URL with no status or message. Skip the request when the job fails, and the monitor goes down once the interval plus grace pass.

Can an UptimeRobot heartbeat monitor use a cron expression?

No. The monitor takes an interval and a grace period, and the help center tells you to set the crontab entry to match the interval. For a schedule such as weekdays at 06:00, the interval has to cover the longest gap, the weekend.

Choose the Agent's Access Before You Paste Anything

CronRadar's agent quickstart offers two ways to start. They differ in one thing: whether the agent can act on your CronRadar workspace. Neither needs a CLI or an agent skill installed.

The Public Prompt: Code Changes Only

Fetch and follow the instructions to set up CronRadar monitoring from https://docs.cronradar.com/agent-setup/prompt.md

This prompt contains no credentials and grants no workspace access. The agent edits code; you create the application and its key in the console's Setup tab and store the key yourself. The public instructions tell an agent without access to send you to the console for a private prompt, so if you want code changes only, say so, as the prompts further down do. The AI setup page has a longer code-only prompt that spells this out.

The Private Setup Prompt: Temporary Workspace Access

At app.cronradar.com/assistant you choose one workspace, the permissions, and an expiry, then copy a private prompt that carries a temporary token. Read access supports investigation, write access allows setup, and delete is a separate choice. Access lasts one hour by default and up to 24 hours, can be revoked at any time, and never exceeds your own workspace role, which is checked on every request. Creating applications and jobs needs a Member role with write access; updating them or creating a deployment key needs Admin with write access.

The agent needs an HTTP or code-execution tool to use the token; a chat-only assistant can explain setup but can't call the management API.

Which One to Use

Pick the shortest expiry that covers the task. A task that outlasts its grant gets fresh access from the console, not a silently extended one.

Keep the Two Credentials Apart

Two credentials are in play, and the most damaging mistake is letting one stand in for the other.

The rules that follow from that split:

• The ingestion key never enters the chat. It is shown once when created. Save it straight into the deployment's secret manager as CRONRADAR_API_KEY; the agent doesn't need the value to write code that reads it.
• The agent creates a key only if it can store it safely. CronRadar's instructions let an agent with Admin and write access create an ingestion key only to save it through an authorized secret-store operation, never printing it. Without such a tool, create the key in the console.
• Assume the transcript outlives the token. Anyone holding the private prompt can use it until it expires or is revoked, and your assistant provider may retain the conversation after expiry. Keep the expiry short, and never paste the prompt into a shared channel or ticket.
• Revoke when you finish, then check what remains. Expiring or revoking access does not undo the agent's changes or revoke ingestion keys it created. Applications and jobs stay in the workspace, and created keys keep deployed monitoring running until their own expiry or revocation. Review them in the application's Setup tab.
• Use one application and key per environment. Production, staging, and development each get their own, so a staging host can't update production monitors.

What a Good Agent Run Looks Like

A careful run follows the same order whichever prompt you used. CronRadar's task recipes describe it for the agent; use it as your yardstick when reading the transcript.

1. It reads before it writes. With workspace access, its first call is GET /context, to confirm the workspace and effective permissions match your request. Then it lists existing applications and jobs, matching environment and stable job key before proposing anything new. A job's management ID and its monitor key differ; check-ins use the key.
2. It keeps environments in separate applications. It reuses the application for this environment or creates one whose environment field describes the actual deployment.
3. It finds the process that actually runs the scheduler. Monitoring belongs where jobs execute: the host with the crontab, the worker service that runs Hangfire Server, the container a Kubernetes CronJob starts. An integration added to a web project does nothing if the jobs run in a separate worker.
4. It checks availability before installing. Repository docs can describe a release that isn't published yet. As of September 20, 2026, the installable packages are CronRadar 1.0.13 (.NET), CronRadar.Hangfire 0.1.0, and CronRadar.Quartz 0.1.0. For Node.js, Python, Celery, PHP, Laravel, and stacks such as Go, Ruby, or plain shell, there is no usable CronRadar SDK and no auto-discovery, so each job reports with its own HTTP check-in. Registries do list cronradar (npm, PyPI) and cronradar-celery (PyPI), but the docs mark them unavailable, so an agent that finds them in a search shouldn't install them.
5. It lets discovery do its job. Framework integrations discover recurring jobs themselves; the base SDK and HTTP check-ins need an explicit report per job. If discovery misses a job, the fix is in the integration, not a duplicate created through the management API.
6. It preserves the job. Same schedule, time zone, retry behavior, and result. It builds and runs the tests, then tells you which process needs a deploy or restart. It doesn't deploy, deliberately fail production work, pause monitoring, or delete anything you didn't ask it to.
7. It reports evidence, then hands access back. The summary separates what changed, what real execution evidence it saw, and what remains unverified, including alert delivery, and ends by telling you to revoke the grant.

For a Hangfire application, a correct diff can be this small:

dotnet add package CronRadar.Hangfire

// Program.cs
using CronRadar.Hangfire;
using Hangfire;

// Existing Hangfire setup stays as it was.
builder.Services.AddHangfire(config =>
    config.UseSqlServerStorage(builder.Configuration.GetConnectionString("Hangfire")));
builder.Services.AddHangfireServer();

// Added after AddHangfire(). The key comes from CRONRADAR_API_KEY.
builder.Services.AddCronRadarHangfire();

The integration reads Hangfire's recurring-job registry at startup, reconciles it every 15 minutes, and reports each execution's start, completion, or failure; [SkipMonitor] on a method opts a job out. Monitoring calls added inside each job method on top of this are duplicated reporting, not extra safety. CronRadar for Hangfire covers what the integration watches.

Prompts You Can Paste

Each states the access boundary, what must not change, and what counts as done.

Add Monitoring to Hangfire Jobs, Code Only

Add CronRadar monitoring to the Hangfire recurring jobs in this repo using the
public setup instructions at https://docs.cronradar.com/agent-setup/prompt.md.
Don't request workspace access, and don't create, ask for, or print any keys.
I'll create the application and key in the console and store CRONRADAR_API_KEY
in our secret manager. Read the Hangfire guide's availability notice first and
use only the published package. Put the integration in the process that runs
Hangfire Server. Keep every schedule, time zone, retry policy, and job result
unchanged. Run the tests, then tell me what needs deploying and how I'll know
a real run reported.

Add HTTP Check-Ins Where There Is No SDK

Read https://docs.cronradar.com/agent-setup/prompt.md. Our scheduled jobs run
from node-cron in worker/index.js, and CronRadar has no available Node.js SDK,
so add HTTP check-ins to each job: start, then complete or fail. Don't install
any CronRadar package. Each check-in must time out after 5 seconds, ignore its
own errors, and leave the job's exception and exit code unchanged. Send the
five-field UTC equivalent of each schedule and read CRONRADAR_API_KEY from the
environment. Don't request workspace access or handle keys.

Investigate a Late Job With Read-Only Access

Create a private prompt with read access only, paste it, then add:

Using read-only access, find out why nightly-invoice-export in the production
application was late last night. Read the job, its recent check-ins, and its
alerts. Compare the expected schedule, time zone, and grace period with the
latest start and terminal events, and tell me whether it never reported, ran
late, failed explicitly, or started without finishing. Don't create, change,
pause, or delete anything. List what I should check in the scheduler itself.

The last sentence matters because the management API exposes check-ins and alerts, not application logs: the agent can say what CronRadar recorded, not why the job behaved that way.

Review the Diff Before You Merge

Reviewing AI-generated cron jobs covers these checks in depth; this is the short list for a monitoring change.

The retry row has a Hangfire-specific trap. Hangfire's automatic retry filter applies 10 retry attempts by default, and the published CronRadar.Hangfire 0.1.0 can report a failure before Hangfire finishes retrying, including cancellations (checked September 20, 2026). Reporting only after retries are exhausted requires the pending 0.2.1 release. An agent asked to quiet those early alerts may reach for [AutomaticRetry(Attempts = 0)], which silences them by changing what the job does. Reject that change.

For the obvious secret leaks, scan the lines the agent added. No output is the result you want:

# Added lines that look like a CronRadar key or a hardcoded bearer token.
git diff main...HEAD | grep -E '^\+.*(ck_app_|Bearer [A-Za-z0-9._~+/=-]{20,})'

This catches a pasted key, not one split across lines or encoded; a repository secret scanner, if you run one, remains the stronger control. For a shell wrapper that passes every row of the table, see the one in the dead man's switch guide.

Verify a Real Run Yourself

A created monitor, a successful API call, an installed package, or a demo incident shows that something was configured, not that the deployed scheduler reports. Activation is a real run from the intended deployment.

1. Confirm the key is present in the deployed environment without printing it:

   test -n "$CRONRADAR_API_KEY" && echo "CronRadar key is set" || echo "CronRadar key is missing"
   

2. Deploy or restart the scheduler process. With a framework integration, the recurring jobs appear in the matching application with the scheduler's current cron expressions. For any job on a non-UTC time zone, compare CronRadar's next expected run with the scheduler's next fire time.

3. Let a real scheduled run happen, or trigger one through the scheduler, then open Applications, your application, Jobs. Confirm it's the right environment's application and the run shows a terminal result: success, failed, or timeout; a start alone means still in progress. Then confirm the next scheduled run arrives, since a manual trigger doesn't exercise the schedule.

4. Send a channel test from the application's Alerts tab and have the intended recipient confirm it arrived. For Slack, invite CronRadar to the public channel before selecting it. A channel test proves delivery, not that a failed job is detected.

5. Exercise failure only in a separate test application, with a harmless job and an agreed test destination. Never fail a production job on purpose, and don't let the agent.

Be wary of an agent that "verifies" by sending a hand-made check-in. That proves only that the network path and key work, and the verification guide warns that doing it with the same key as framework-discovered jobs can hide a discovery or lifecycle wiring problem. An agent with read access can report the check-in timestamps it sees; look at the first one yourself anyway.

When the scheduled job itself calls an LLM or runs an agent, monitoring scheduled AI agent runs covers the failures that still exit 0, such as rate limits, truncated output, and refusals. When the scheduled job is the coding agent itself, with claude -p or codex exec running from cron or CI, scheduled coding agent runs covers its permissions, limits, and exit codes.

Optional: Connect Over MCP

MCP is not required; the private prompt works over the management REST API. If your client supports remote MCP servers with a configurable bearer header, you can keep the temporary token in its secret configuration instead of the conversation. The CronRadar MCP server guide covers setup in each client and what its tools can and can't do.

There is no OAuth sign-in and no automatic token refresh: when the token expires, create fresh access in the console and update the secret. MCP enforces the same workspace permissions and expiry as REST, and its tools mirror the REST operations, starting with get_context.

In Claude Code, .mcp.json expands environment variables in headers (checked October 24, 2026), so the file holds only a variable name:

{
  "mcpServers": {
    "cronradar": {
      "type": "http",
      "url": "https://api.cronradar.com/api/agent/mcp",
      "headers": {
        "Authorization": "Bearer ${CRONRADAR_AGENT_TOKEN}"
      }
    }
  }
}

Set CRONRADAR_AGENT_TOKEN from your password manager when you start the session; in interactive sessions, Claude Code asks for approval before using a server from a project's .mcp.json. Other clients have their own secret mechanisms; use the one their documentation describes rather than writing the token into a config file.

Treat Job Data as Data

When an agent reads monitoring data, it reads text your jobs and teammates wrote: job names, descriptions, and failure messages. CronRadar's instructions tell the assistant these are application data, not instructions. That matters because a failure message can carry text from elsewhere, such as an exception quoting an upstream API's response. Instructions planted in content an LLM reads from external sources are what OWASP calls indirect prompt injection in LLM01:2025, and two of its listed mitigations apply here: mark untrusted content as such, and restrict the model to the minimum privileges it needs. Give investigation sessions read-only access, and keep failure messages free of payloads, logs, and customer data, as the ingestion API already asks.

Frequently Asked Questions

Can Claude Code or Cursor set up cron job monitoring for me?

Yes. Any coding agent that can edit your repository can add a framework integration or HTTP check-ins, and one with an HTTP or code-execution tool can also use temporary workspace access to inspect existing monitors and read back check-ins. You still review the diff and confirm a real run.

Is it safe to give an AI agent an API token for monitoring?

It's a reasonable risk when the token is scoped and short-lived: one workspace, the least permission the task needs, the shortest expiry that fits, and revoked when you finish. Anyone holding the prompt can use it until then, and the assistant provider may keep the transcript. Never give the agent the long-lived deployment key.

Do I need an MCP server to use CronRadar with an AI agent?

No. The private setup prompt works over the management REST API with any agent that can make HTTP requests. MCP is an optional alternative for clients that support remote servers with a bearer header.

What should I check after an AI agent adds monitoring?

Review the diff for missing timeouts, swallowed exceptions, changed exit codes or retries, schedules that aren't five-field UTC, secrets, and duplicate monitors. Then deploy and confirm that a real scheduled run shows a terminal result in the right application and that a channel test reaches the intended recipient.

What happens to changes when the agent's access expires?

Nothing is undone. Applications and jobs the agent created stay, and ingestion keys it created keep working until their own expiry or revocation, so review them in the application's Setup tab and revoke any the deployment doesn't use.

This guide covers Apache Airflow 3.3.2, released September 17, 2026 and the current stable release when checked on October 25, 2026, with Airflow 2.11 noted where defaults changed. Source links point to the 3.3.2 tag.

How Airflow Decides When a Run Starts

A DAG's schedule accepts a cron expression or preset such as "@daily", a timedelta, a timetable object, or a list of assets, which trigger the DAG when another task updates them (DAG source). Assets were called datasets in Airflow 2. Airflow 3.0 removed schedule_interval and made None the default schedule, so a DAG without one runs only when triggered (3.0.0 release notes).

Trigger Time and Logical Date

In Airflow 3, a cron string runs on CronTriggerTimetable: a run's logical date is the moment it's scheduled to start, and its data interval has no length. Airflow 2 used CronDataIntervalTimetable, where each run covers the period between two cron times, starts when that period ends, and is labeled with the period's start. The [scheduler] create_cron_data_intervals setting chooses between them and defaults to False in Airflow 3 and True in 2.x (configuration). Both kinds start runs at the same moment (timetables). For a @daily DAG in UTC:

A monitor needs only the start time, which is the cron expression itself: 0 0 * * *. What changes is the date your tasks see. Templated values such as ds derive from logical_date (upgrade guide), so a task that loads the day in {{ ds }} loads a different day after an upgrade that switches timetables, and still finishes on time and successfully. That's the failure checks on what a run produced exist for. Switching an existing DAG from a trigger timetable to a data-interval one also skips one scheduled run (timetables).

Catchup, start_date, and max_active_runs

catchup decides what happens to schedule points that pass while a DAG is paused or the scheduler is down. Its default, [scheduler] catchup_by_default, is False in Airflow 3 and was True in 2.x. With it off, the scheduler creates a run only for the latest interval; with catchup=True, it creates one for every interval that hasn't run (DAG runs). Missed runs after downtime compares this with other schedulers.

No run is scheduled before start_date. max_active_runs caps the DAG's active runs, 16 by default from [core] max_active_runs_per_dag, and at the cap the scheduler creates no new runs (configuration).

The Components That Have to Be Running

The scheduler creates DAG runs and hands ready tasks to the executor, which runs inside the scheduler process. The DAG processor parses DAG files into the metadata database, where the scheduler reads them (architecture). In Airflow 3 the DAG processor is a separate process started with airflow dag-processor, even in development (upgrade guide); in Airflow 2.11 it ran inside the scheduler unless standalone_dag_processor was set (2.11 configuration).

Time Zones

Airflow stores times in UTC and applies [core] default_timezone, utc unless changed, to naive datetimes. A DAG takes its time zone from a pendulum start_date, and cron schedules follow that zone's daylight saving time: a 0 0 * * * DAG in US/Eastern runs at 04:00 UTC in summer and 05:00 UTC in winter. Airflow's docs recommend authoring DAGs in UTC where you can (time zones). Cron daylight saving time covers the transition nights.

Why an Airflow DAG Didn't Run on Schedule

The pause default is in the configuration reference; a DAG can opt out with is_paused_upon_creation=False. The experimental max_consecutive_failed_dag_runs is 0, never, unless someone set it (DAG source). The DAG processor looks for new files every [dag_processor] refresh_interval, 300 seconds by default (configuration), and Airflow's FAQ advises against a datetime.now() start date because the first run keeps moving with it (FAQ). Tasks without a pool share default_pool, 128 slots, and wait once it's full (pools); parallelism allows 32 running task instances per scheduler, and max_active_tasks, 16 by default, applies per run since Airflow 3 (configuration, DAG source).

SLAs in Airflow 2, Deadline Alerts in Airflow 3

Airflow 2 had task SLAs: sla=timedelta(...) on a task, misses listed under SLA Misses in the UI and emailed, and an optional DAG-level sla_miss_callback. Tasks over their SLA kept running, and manually triggered runs and event-driven DAGs weren't checked (Airflow 2.11 SLAs). Airflow 3.0 removed the feature (upgrade guide), but 3.3.2 still accepts sla and sla_miss_callback and only warns that SLAs are gone (operator, DAG), so a migrated DAG parses and never alerts.

Deadline Alerts replaced them in Airflow 3.1 and are still marked experimental in the 3.3.2 docs (Deadline Alerts). A DeadlineAlert adds an interval to a reference point (DAGRUN_QUEUED_AT, DAGRUN_LOGICAL_DATE, FIXED_DATETIME, or AVERAGE_RUNTIME) and runs a callback if the DAG run hasn't finished by then. An AsyncCallback runs in the triggerer; a SyncCallback, added in 3.2, is sent to the executor like a task. With the Slack provider installed, on Airflow 3.2 or later:

from datetime import timedelta

from airflow.providers.slack.notifications.slack_webhook import SlackWebhookNotifier
from airflow.providers.standard.operators.empty import EmptyOperator
from airflow.sdk import DAG, AsyncCallback, DeadlineAlert, DeadlineReference

with DAG(
    dag_id="nightly_orders_deadline",
    schedule="0 2 * * *",
    deadline=DeadlineAlert(
        reference=DeadlineReference.DAGRUN_QUEUED_AT,
        interval=timedelta(hours=1),
        callback=AsyncCallback(
            SlackWebhookNotifier,
            kwargs={"text": "{{ dag_run.dag_id }} missed its deadline at {{ deadline.deadline_time }}"},
        ),
    ),
):
    EmptyOperator(task_id="load_orders")

On 3.1, import AsyncCallback from airflow.sdk.definitions.deadline. Two limits matter for scheduling problems. First, Airflow computes a deadline when it creates the DAG run, and the scheduler loop checks for passed deadlines (migration guide, source), so a run that was never created has no deadline and a stopped scheduler checks none. Second, DAGRUN_LOGICAL_DATE counts from the logical date, which on a data-interval timetable is a full period before the run starts; use DAGRUN_QUEUED_AT there.

Callbacks Only Cover Runs That Exist

on_success_callback and on_failure_callback can be set on the DAG or on tasks; tasks also have retry, execute, and skipped callbacks (callbacks). Where they run decides what they need:

• DAG-level callbacks run in the DAG processor. When a run ends, the scheduler sends it a request; a failed run's reason is task_failure, timed_out for a run past dagrun_timeout, or all_tasks_deadlocked (processor, DAG run, scheduler). Their errors go to DAG processor logs, not task logs.
• Task-level callbacks run in the task's process on the worker, after the task finishes (task runner). If that process dies without reporting, the scheduler fails the task and has the DAG processor run its failure callback (scheduler).
• Neither fires for a state you set in the UI or CLI.

Why an External Check Still Helps

If the scheduler stops, no runs are created, so no task, callback, or deadline runs, and nothing inside Airflow reports it. Airflow's /api/v2/monitor/health endpoint and airflow jobs check show whether the scheduler, DAG processor, and triggerer are heartbeating (health checks), but something outside has to poll them, and a healthy scheduler says nothing about a paused DAG or one that failed to import. A schedule monitor works from the other side: each run reports, and the monitor, running outside Airflow, alerts when an expected report doesn't arrive, whatever stopped it.

Report Each DAG Run to CronRadar

There's no CronRadar SDK for Airflow, the Python SDK isn't installable (checked September 20, 2026), and nothing discovers DAGs automatically, so each DAG reports with its own HTTP check-ins. Airflow's core package already depends on requests (pyproject.toml). This DAG sends start from its first task, complete from its last, and fail from a DAG-level failure callback:

# dags/nightly_orders_etl.py
import hashlib
import logging
import os
from datetime import timedelta

import pendulum
import requests
from airflow.providers.standard.operators.bash import BashOperator
from airflow.sdk import dag, task

log = logging.getLogger(__name__)

# The DAG runs in UTC, so Airflow and CronRadar read this expression the same way.
SCHEDULE = "0 2 * * *"
CHECK_IN_URL = "https://cron.life/api/v1/ping/nightly-orders-etl"


def check_in(event, airflow_run_id, message=None):
    """Report one event to CronRadar. Never raises into Airflow."""
    try:
        run_id = airflow_run_id
        if len(run_id) > 128:  # CronRadar's limit; Airflow allows 250
            run_id = hashlib.sha256(run_id.encode()).hexdigest()
        params = {"schedule": SCHEDULE, "gracePeriod": 900, "run_id": run_id}
        if message:
            params["message"] = message[:1000]
        response = requests.post(
            f"{CHECK_IN_URL}/{event}",
            params=params,
            auth=(os.environ["CRONRADAR_API_KEY"], ""),
            timeout=5,
        )
        response.raise_for_status()
    except Exception as error:
        log.warning("CronRadar %s not recorded (%s)", event, type(error).__name__)


def report_failed_run(context):
    """DAG-level failure callback. The DAG processor runs it, not a worker."""
    ti = context.get("ti")
    task_note = f", task {ti.task_id}" if ti is not None else ""
    check_in("fail", context["run_id"], f"Airflow run failed ({context.get('reason')}{task_note})")


@dag(
    schedule=SCHEDULE,
    start_date=pendulum.datetime(2026, 10, 1, tz="UTC"),
    catchup=False,
    max_active_runs=1,
    dagrun_timeout=timedelta(hours=3),
    on_failure_callback=report_failed_run,
    default_args={"retries": 2, "retry_delay": timedelta(minutes=5)},
)
def nightly_orders_etl():
    @task
    def report_start(**context):
        check_in("start", context["run_id"])

    load_orders = BashOperator(
        task_id="load_orders",
        bash_command="python /opt/etl/load_orders.py",
        execution_timeout=timedelta(minutes=45),
    )

    # all_success is the default; it's written out so nobody switches it to all_done.
    @task(trigger_rule="all_success")
    def report_complete(**context):
        check_in("complete", context["run_id"])

    report_start() >> load_orders >> report_complete()


nightly_orders_etl()

• The run ID is the DAG run's own, such as scheduled__2026-10-25T02:00:00+00:00, so start and the terminal event pair up across task retries. Airflow allows 250 characters (source) and CronRadar 128, so longer manual run IDs are hashed.
• The trigger rule matters because a leaf task with all_done runs after failures, and if it succeeds the whole run is marked successful (DAG runs).
• The key has to be in the environment of the workers and the DAG processor, which runs the failure callback. Use one CronRadar application and key per Airflow environment. An existing failure callback can stay: pass a list, [notify_team, report_failed_run].
• Timeouts turn hangs into fail once retries run out. Without them, a hang leaves a start with no finish, which CronRadar flags as stuck only if the next run's expected time plus grace passes with no check-in; with max_active_runs=1 the hung run also blocks the next one, so that happens at the next due time.
• timeout=5 limits connecting and each wait for data, not the whole request (requests).

Alerts go to email, Slack, a webhook, Discord, or PagerDuty. Because every check-in carries the schedule, the first one creates the monitor and a deleted monitor comes back on the next run. But new DAGs start paused, and a monitor created by its first check-in can't flag a DAG that never runs. Create the monitor in the CronRadar dashboard before deploying, with the same key, schedule, and grace: it stays pending, and CronRadar sends a never-executed alert if the first expected run plus grace passes with no report.

A run that loads zero rows still sends complete. To catch that, report counts as bounded outcomes; ETL job monitoring shows which numbers to send.

Choose the Schedule and Grace Period to Send

Send the time the run should start, in UTC, as a five-field expression (schedule syntax):

Sources: the # syntax is on Airflow's cron page, Airflow's schedule description reads two restricted day fields as "or" (source), and the timedelta alignment is in the timetable comparison.

An asset-triggered DAG runs whenever an upstream task updates the asset, so no time says a run is due, and a CronRadar monitor needs a cron schedule. It can't be represented. Monitor the time-scheduled DAG that produces the asset, or a scheduled job that checks the data's freshness and sends its own heartbeat, as ETL job monitoring describes.

The grace period has to cover the delay before report_start runs, while the scheduler creates the run and a worker picks up the task. Compare recent runs' scheduled times with report_start's start times in the UI and take the worst case plus a margin. A pod per task or a full pool at 02:00 can take minutes, so CronRadar's 90-second default may be too short; cron grace period works through the arithmetic. schedule and gracePeriod apply only when a check-in creates the monitor; change them later in its settings. Then compare airflow dags next-execution nightly_orders_etl --field run_after -n 3 with CronRadar's next expected run, especially for a DAG outside UTC.

Catch a Stopped Scheduler Sooner

With one monitor per DAG, a stopped scheduler shows up as each DAG goes overdue, and a daily DAG may not be due for hours. A canary DAG closes the gap: one task on */10 * * * * that posts a heartbeat to https://cron.life/api/v1/ping/airflow-canary, with no event suffix, schedule=*/10 * * * *, and the same requests options. Give the DAG is_paused_upon_creation=False, catchup=False, and max_active_runs=1. If the scheduler or the workers stop, the canary misses a check-in and goes critical after its grace period, and the per-DAG monitors show which pipelines missed runs.

Frequently Asked Questions

Why is my Airflow DAG not running on schedule?

Check whether it's paused first: new DAGs start paused because dags_are_paused_at_creation defaults to True. Then run airflow dags list-import-errors, and confirm the DAG has a schedule, which Airflow 3 doesn't set by default, and a fixed start_date in the past. After that, look for a previous run holding max_active_runs or tasks waiting for pool slots. If no DAG is running, check the scheduler and the DAG processor.

Does Airflow 3 still have SLAs?

No. Airflow 3.0 removed SLAs, and the sla and sla_miss_callback arguments now only produce a warning. Deadline Alerts, added in 3.1 and still experimental in 3.3, run a callback when a DAG run hasn't finished by a deadline measured from when it was queued, its logical date, a fixed time, or its average runtime. They only cover runs that were created, while the scheduler is running.

What does catchup do in Airflow?

It decides whether the scheduler creates runs for schedule points missed while a DAG was paused or the scheduler was down. With catchup=True it creates one run per missed interval; with catchup=False, the default since Airflow 3.0, it creates only the latest, and nothing in Airflow flags the skipped ones.

When does a daily Airflow DAG actually run?

At 00:00 in the DAG's time zone. In Airflow 2, and in Airflow 3 with create_cron_data_intervals=True, the run that starts at 00:00 on October 25 has a logical date of October 24, because it covers that day; Airflow 3's default timetable labels it October 25. The schedule a monitor needs is the same either way: 0 0 * * * for a DAG in UTC.

How do I get alerted if the Airflow scheduler stops?

Use a monitor outside Airflow that notices silence, because a stopped scheduler runs no callbacks or deadlines. Check-ins from each DAG run alert when a run doesn't report, and a canary DAG checking in every ten minutes turns a stopped scheduler into a missed check-in within ten minutes plus its grace period. Airflow's health endpoint and airflow jobs check --job-type SchedulerJob report the scheduler's heartbeat, but need an external poller.

Checked October 25, 2026, against two implementations. Cronie 1.7.2, which includes anacron, is what Fedora and Arch ship; RHEL 9 has cronie 1.5.7 and RHEL 10 has 1.7.0 (CentOS Stream 9, 10), with the same anacron code apart from the battery switch. Debian and Ubuntu package anacron 2.3 on its own, even alongside cronie (rules): 2.3-43 in Debian 13, 2.3-39 in Ubuntu 24.04, and 2.3-45 in Ubuntu 26.04 (Debian, Ubuntu).

How Anacron Decides a Job Is Due

Anacron keeps one timestamp file per job in /var/spool/anacron, named after the job and holding a single date such as 20261025. When it starts, it subtracts that date from today's. If the difference is at least the job's period in days, the job is due: anacron waits the job's delay, counted in minutes from when anacron itself started, runs the command with /bin/sh -c, and writes the date when the command exits (anacron(8), lock.c, main.c). Debian's 2.3 code works the same way (lock.c).

What follows from that:

• Daily means once per calendar date, not every 24 hours. Only the date is stored, so a job that ran at 23:40 is due again just after midnight if anacron starts then. A stored date in the future, after the clock was set back, also makes it due.
• A failed run counts as a run. The date is written whatever the exit status (runjob.c), so a script that failed waits for its next period.
• Output is mailed, or lost. Anything a job prints goes to MAILTO, or to the user running anacron, through /usr/sbin/sendmail. Without it, anacron logs that it can't find sendmail and discards the output (runjob.c).

The /etc/anacrontab Format

These are the settings and jobs in Fedora's default file, from cronie 1.7.2 (anacrontab):

SHELL=/bin/sh
PATH=/sbin:/bin:/usr/sbin:/usr/bin
MAILTO=root
# the maximal random delay added to the base delay of the jobs
RANDOM_DELAY=45
# the jobs will be started during the following hours only
START_HOURS_RANGE=3-22

#period in days   delay in minutes   job-identifier   command
1	5	cron.daily		nice run-parts /etc/cron.daily
7	25	cron.weekly		nice run-parts /etc/cron.weekly
@monthly 45	cron.monthly		nice run-parts /etc/cron.monthly

Debian 13's default has the same three jobs with delays of 5, 10, and 15 minutes, adds @yearly 20 cron.yearly, sets HOME and LOGNAME, and has neither scheduling variable (anacrontab). Ubuntu's leaves out the PATH line, and 24.04's has no yearly job.

Which period names work depends on the version:

That comes from cronie's readtab.c, Debian's readtab.c, and Debian's changelog for 2.3-44. @monthly runs once a month whatever its length; write daily and weekly periods as 1 and 7, which every version reads the same way.

Environment Lines and the Two Scheduling Variables

A NAME=value line sets an environment variable for every job below it. SHELL is only passed along: both implementations run commands with /bin/sh -c whatever it says (cronie, Debian). MAILTO picks the mail recipient; on cronie, an empty one turns mail off. Cronie's anacron also reads two lines as settings:

• RANDOM_DELAY=45: each time anacron starts, it picks one random number from 0 to 45 and adds it to the delay of every job listed after that line (readtab.c).
• START_HOURS_RANGE=3-22: a due job is skipped unless its start time, anacron's start plus the delay, falls between 03:00 and 21:59; a missed window means no run that day (lock.c, anacrontab(5)).

Debian's anacron 2.3 has neither. It passes both lines to jobs as ordinary environment variables, so a START_HOURS_RANGE copied from a Fedora guide does nothing, and anacron -T won't flag it.

One gap in cronie 1.7.2: the hours check runs only when the job's timestamp file already holds a date. A new job, or a fresh install with empty timestamp files, runs at the next hourly start at any hour. The fix was merged in October 2026 and isn't in a release yet (#248).

When /etc/cron.daily Runs

Times are the host's local time. Without anacron, cron runs the directories only if the machine is up at that minute, and a missed day is gone; missed runs after downtime compares what other schedulers do.

Fedora, RHEL, and Arch

Crond runs run-parts /etc/cron.hourly at one minute past every hour (0hourly). The first script there, 0anacron, exits at once if /var/spool/anacron/cron.daily already holds today's date or the machine is on battery, and otherwise starts anacron -s (0anacron). With the defaults, the 03:01 start is the first that can put cron.daily inside 3-22, hence 03:06 to 03:51. When the weekly and monthly jobs are due, they follow in the same run, one at a time because of -s.

Because of that early exit, anacron isn't started again once cron.daily has run that day, so a job you add to /etc/anacrontab later in the day is first considered the next morning.

Fedora's cronie requires a package that provides dailyjobs: cronie-anacron, or cronie-noanacron, which runs the directories from fixed cron lines at 04:02 daily, 04:22 on Sundays, and 04:42 on the 1st (cronie.spec, dailyjobs).

Debian and Ubuntu

/etc/crontab still runs the directories at 06:25 daily, 06:47 on Sundays, and 06:52 on the 1st, but each line begins with test -x /usr/sbin/anacron || and does nothing once anacron is installed (crontab); Ubuntu 24.04's is identical. On systemd hosts, anacron.timer fires on the half hour from 07:30 to 23:30, up to five minutes late at random, with Persistent=true (anacron.timer), and anacron.service also starts at boot, running anacron -d -q -s (anacron.service, default). With no hours range, a host booted at 02:00 runs cron.daily at 02:05. Without systemd, /etc/cron.d/anacron starts anacron at the same :30 times (cron.d).

Debian's /etc/cron.daily/0anacron runs anacron -u cron.daily, so running the directory by hand with run-parts also updates the timestamp (0anacron).

Why cron.daily Didn't Run Today

• Anacron thinks it already ran. Today's date in /var/spool/anacron/cron.daily ends the question, even if that run failed or the date came from anacron -u.
• The machine wasn't up in the window. With cronie's defaults, a host that comes up after about 21:00 waits until after 03:00 tomorrow, and a host that is only on between 22:00 and 03:00 never runs it.
• It's on battery. Debian's service has ConditionACPower=true; a skipped start logs a line ending was skipped because of an unmet condition check (ConditionACPower=true) (job.c), and README.Debian shows the drop-in that removes the check. Cronie's 0anacron exits when every mains supply in /sys/class/power_supply is offline; on Fedora and RHEL 10, ANACRON_RUN_ON_BATTERY_POWER=yes in /etc/default/anacron overrides it, and RHEL 9's 1.5.7 has no override (1.5.7).
• Nothing started anacron. On cronie, crond has to be running (crond.service; on Arch, cronie.service), and 0anacron listed in /etc/cron.hourly/jobs.deny disables it (anacrontab(5)). On Debian, systemctl list-timers anacron.timer should show a next run.
• Run-parts skipped the script. Both run-parts versions skip files that aren't executable. Debian's runs only names made of letters, digits, underscores, and hyphens, so backup.sh never runs (run-parts(8)). Fedora's allows dots, but skips names ending in ~, .rpmnew, .rpmsave, and similar, and any name listed in that directory's jobs.deny (run-parts).
• The script exits on purpose. Debian 13's /etc/cron.daily/logrotate exits on systemd hosts, where logrotate.timer rotates logs instead (patch); systemctl list-timers shows work that moved to timers.
• Yesterday's run is still going. Anacron locks a job while it runs, and cronie's next start logs locked by another anacron - skipping. On Debian the service is still active, and a timer doesn't start a unit that is already running (systemd.timer(5)).

These commands answer most of those questions:

# Last-run date per job (YYYYMMDD), and when each file was last written
ls -l --time-style=long-iso /var/spool/anacron
sudo head /var/spool/anacron/*

# Anacron's log lines, on either family
sudo journalctl -t anacron --since yesterday

# Debian and Ubuntu: the timer's next run, and starts skipped on battery
systemctl list-timers anacron.timer
sudo journalctl -u anacron.service --since yesterday

# What run-parts would run, without running it
run-parts --test /etc/cron.daily

Anacron logs to syslog with facility cron (anacron(8)). The lines to look for, with example values:

Anacron started on 2026-10-25
Will run job `cron.daily' in 17 min.
Job `cron.daily' started
Job `cron.daily' terminated (exit status: 1)
Job `cron.daily' locked by another anacron - skipping
Normal exit (0 jobs run)

Debian's first line reads Anacron 2.3 started on, and the minutes in Will run job include any random delay. Normal exit (0 jobs run) means nothing was due or, on cronie, that a due job's start time fell outside START_HOURS_RANGE, a skip anacron doesn't log separately (lock.c). No anacron lines at all after the daily run is normal on cronie, since 0anacron stops starting it. If the daily job ran, the problem is in a script; cron job not running covers paths, environment, and permissions.

Running Anacron by Hand

# Check /etc/anacrontab; exit status 0 means no errors
sudo anacron -T

# Run cron.daily now, ignoring its timestamp and delay, in the foreground
sudo anacron -d -f -n cron.daily

# Record cron.daily as done today without running it
sudo anacron -u cron.daily

The options are the same in both: -f ignores timestamps, -n ignores delays and implies -s, -s runs jobs one at a time, -d stays in the foreground and prints anacron's messages, -q hides them, -u updates timestamps without running anything, and -T checks the file, printing a line such as anacron: Invalid syntax in /etc/anacrontab on line 14 - skipping this line. Arguments are job identifiers or quoted shell patterns such as 'cron.*'. -t and -S pick another anacrontab and spool directory, which is how an ordinary user runs a personal anacron. On cronie, -f and -n also bypass START_HOURS_RANGE. Job output is still mailed rather than printed, so run a script directly to watch it.

Changing When Daily Jobs Run

On cronie, edit the variables. START_HOURS_RANGE=1-5 with RANDOM_DELAY=0 runs cron.daily at 01:06 on a host that is up, or at the first start after boot before 05:00.

On Debian and Ubuntu, override the timer with sudo systemctl edit anacron.timer:

# /etc/systemd/system/anacron.timer.d/override.conf
[Timer]
OnCalendar=
OnCalendar=*-*-* 01..05:30

The empty OnCalendar= clears the packaged schedule before the new one is added (systemd.timer(5)). The start at boot remains, because multi-user.target starts anacron.service directly.

Anacron vs Cron vs systemd Timers

Anacron suits work that should happen once a day or less on machines that aren't always on, when the exact hour doesn't matter. A timer can do the same catch-up at a time you choose, with logs in the journal (systemd timers); systemd timers vs cron covers moving a job over. The crontab guide has a script that lists every schedule on a host, anacron's included.

Monitoring an Anacron Job

Anacron logs a run and mails its output, but nothing reports a day it didn't run. A check-in monitor does: the job reports to CronRadar when it starts and finishes, and CronRadar alerts when an expected report doesn't arrive. There is no CronRadar SDK for anacron and no auto-discovery, so each job reports with its own HTTP check-in.

CronRadar has no "once a day, any time" setting: a monitor expects each run at a five-field cron time, evaluated in UTC, plus a grace period, and every check-in moves the expectation to the next scheduled time. Set the schedule to the earliest time the job can start and make the grace period reach past the latest. A run earlier than the schedule breaks this, because its check-in only moves the expectation to that same day's time, which then passes with nothing arriving.

Take a job added to cronie's default anacrontab with a 15-minute delay, on a server that stays up and keeps its clock in UTC:

1	15	daily-backup	/usr/local/bin/daily-backup-monitored.sh

• Earliest start: 03:00. START_HOURS_RANGE=3-22 keeps any job from starting earlier.
• Latest start: about 04:01, the 03:01 run plus 15 minutes plus the full 45-minute random delay, later if cron.daily is still running, because -s makes jobs wait their turn.
• So schedule=0 3 * * * with gracePeriod=7200 puts the deadline at 05:00, which covers a cron.daily run of up to about an hour. The monitor shows warning each morning from 03:00 until the start arrives; only critical, past the grace period, opens an incident.

On a laptop or a VM that is shut down overnight, the job can start any time until about 22:00, so the same schedule needs gracePeriod=72000 (20 hours), and a day the machine stays off alerts at 23:00. On Debian and Ubuntu, the start at boot can come at any hour, so use local midnight as the schedule with a grace period under 24 hours, or move a job that needs a predictable time to a cron line or a timer. If the host's clock isn't on UTC, convert, and with daylight saving time use the earlier UTC time and an extra hour of grace (schedule syntax).

The wrapper reports the start, runs the job, and reports complete or fail with the job's own exit code. Each report gives up after five seconds and ignores errors:

#!/bin/sh
# /usr/local/bin/daily-backup-monitored.sh, started by anacron as daily-backup.
# /etc/anacrontab is world-readable, so the key lives in a root-only file.
CRONRADAR_API_KEY=$(cat /etc/cronradar/api-key 2>/dev/null)
url="https://cron.life/api/v1/ping/daily-backup"
run_id="daily-backup-$(date +%s)-$$"

report() {
  event=$1
  shift
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    --request POST --get --user "$CRONRADAR_API_KEY:" \
    --data-urlencode "schedule=0 3 * * *" \
    --data-urlencode "gracePeriod=7200" \
    --data-urlencode "run_id=$run_id" \
    "$@" "$url/$event" || true
}

report start
/usr/local/bin/daily-backup.sh
rc=$?
if [ "$rc" -eq 0 ]; then
  report complete
else
  report fail --data-urlencode "message=daily-backup.sh exited with code $rc"
fi
exit "$rc"

After adding the line, run sudo anacron -u daily-backup once. Cronie 1.7.2 skips the hours check for a job with an empty timestamp file, so the first run could land just after midnight, and its check-in would move the expectation only to 03:00 that day. With today's date recorded, the first run waits for the next morning's window.

The first check-in creates the monitor. schedule and gracePeriod apply only then; change them later in the monitor's settings. A fail alerts immediately. A start with no finish shows as stuck only once the next day's deadline passes, so give the backup its own time limit, for example with timeout, to turn a hang into a failure.

Frequently Asked Questions

What is the difference between cron and anacron?

Cron is a daemon that starts each job at the minute its schedule names, and only if the machine is up then. Anacron is a program that cron or a systemd timer starts; it runs any job whose period in days has passed since the date in its timestamp file, then exits. Cron handles exact times and intervals down to a minute; anacron handles daily, weekly, and monthly work on machines that aren't always on.

When does /etc/cron.daily run?

On a host that stays up, at about 03:06 to 03:51 local time on Fedora, RHEL, and Arch, and 07:35 to 07:40 on Debian and Ubuntu with anacron. After downtime it runs soon after boot, inside cronie's 03:00 to 22:00 window or at any hour on Debian. Without anacron, cron runs it at a fixed time and skips it if the machine is off.

Why didn't cron.daily run today?

Check /var/spool/anacron/cron.daily first: today's date there means anacron counts the day as done, even after a failed run. Otherwise, look for a machine that was off or on battery during the window, a stopped crond or disabled anacron.timer, or a script run-parts skips for its name or a missing execute bit.

Can anacron run jobs more than once a day?

No. Periods are whole days and the timestamp file holds only a date, so the most often a job can run is once per calendar date. For hourly or more frequent work, use a cron line or a systemd timer.

How do I force anacron to run now?

Run sudo anacron -d -f -n cron.daily to run that job at once, in the foreground, ignoring its timestamp and delay; leave out the job name to run every job. On Debian and Ubuntu, sudo systemctl start anacron.service runs only the jobs that are due, with their delays, and does nothing on battery.

EventBridge Scheduler vs. EventBridge Scheduled Rules

EventBridge has two ways to run something on a schedule, and both accept the same cron() and rate() syntax. Scheduled rules are, in AWS's words, "a legacy feature of EventBridge", and "We recommend that you use Scheduler to invoke targets on a schedule" (scheduled rules). Features and default quotas, checked October 25, 2026:

Sources: Scheduler features, targets, and quotas; rule schedules, permissions, retries, and quotas. The rest of this guide covers Scheduler.

The cron() Expression Format

Three rules trip up anyone coming from crontab (schedule types):

• One day field must be ?. You can't restrict both day fields or use * in both: "If you use it in one, you must use ? in the other."
• Sunday is 1. 2-6 is Monday through Friday, so a crontab's 1-5 pasted in becomes Sunday through Thursday. Names such as MON-FRI mean the same everywhere.
• The year is required. Use * for every year.

In day-of-month, L is the last day and 15W the weekday nearest the 15th. In day-of-week, 6L is the last Friday and 2#1 the first Monday. Expressions that would fire more than once a minute aren't supported (troubleshooting), and a run lands anywhere in its minute: a schedule for 1:00 "will invoke the target API between 1:00:00 and 1:00:59."

rate() and at() Expressions

rate(value unit) takes minutes, hours, or days, as in rate(5 minutes). The schedule's StartDate sets the first occurrence; without one, it "starts invoking the target immediately." The interval is fixed, but the clock times depend on when it started. rate(1 days) is 24 hours of real time, so its local time moves an hour at each daylight saving change.

at(2026-11-20T13:00:00) runs once. A completed one-time schedule still counts against the quota, so set ActionAfterCompletion to DELETE (CreateSchedule).

Time Zones and Daylight Saving Time

Set ScheduleExpressionTimezone to an IANA name such as America/New_York for cron() and at() schedules; without it they run in UTC. Scheduler follows the zone's daylight saving changes: an invocation in the hour the spring change skips "is skipped", and one in the hour the fall change repeats runs once (daylight saving). Cron daylight saving time compares this with other schedulers.

Flexible Time Windows

Every schedule must set FlexibleTimeWindow. {"Mode": "OFF"} invokes the target in the scheduled minute; {"Mode": "FLEXIBLE", "MaximumWindowInMinutes": 15} invokes it at some point in the 15 minutes after the scheduled time, which "improves the reliability of your schedule by dispersing your target invocations" (flexible time windows). The window can be 1 to 1,440 minutes (FlexibleTimeWindow). It only moves runs later, so anything waiting for the result must allow the scheduled time plus the window plus the run time.

Delivery, Retries, and Dead-Letter Queues

Scheduler "provides at-least-once event delivery to targets" (features), so one occurrence can reach the target twice. Idempotent scheduled jobs shows how to claim each period before doing its work; putting <aws.scheduler.scheduled-time> in the schedule's Input gives the job that period's key (context attributes).

Retry Policy

When the call to the target fails, Scheduler retries with exponential backoff until either limit in the schedule's RetryPolicy runs out (RetryPolicy): MaximumRetryAttempts, 0 to 185, or MaximumEventAgeInSeconds, 60 to 86,400. Set both. A daily job retried for 24 hours can collide with the next day's run.

Dead-Letter Queues

When an invocation fails for good, Scheduler can send the event to the standard SQS queue (not FIFO) in DeadLetterConfig, if the execution role has sqs:SendMessage (DLQ). Each message carries the target API's ERROR_CODE and ERROR_MESSAGE, SCHEDULED_TIME, and RETRY_ATTEMPTS. Without a DLQ, an event that exhausts its retries shows up only in the InvocationDroppedCount metric.

Scheduler Failures vs. Job Failures

Scheduler's part ends when the target's API accepts the call:

• Lambda. Scheduler invokes functions asynchronously (Lambda guide), so the call succeeds once Lambda queues the event. If the function throws or times out, Lambda runs it "two more times, with a one-minute wait between the first two attempts, and two minutes between the second and third attempts" (async error handling). The function's own MaximumRetryAttempts (0-2) and MaximumEventAgeInSeconds (60-21,600) tune that (PutFunctionEventInvokeConfig), and an on-failure destination records events that fail every attempt.
• ECS. Scheduler calls RunTask. A task that exits non-zero or fails to pull its image isn't a Scheduler failure; ECS reports why it stopped in ECS Task State Change events (task events).
• Step Functions. Scheduler calls StartExecution; an execution that fails later is the state machine's failure.

So the schedule's DLQ holds failed invocations, such as a permissions error, while errors the function returns go to the function's own DLQ or destination (SAM ScheduleV2). Retrying failed cron jobs covers choosing which layer retries.

CloudWatch Metrics for EventBridge Scheduler

Scheduler publishes these in the AWS/Scheduler namespace (metrics):

Two limits matter for alarms. The only dimension is ScheduleGroup, so an alarm watches a group, not a schedule; give an important schedule its own group (500 groups per Region by default) to alarm on it alone. And the metrics are best-effort: "A data point for a given minute might be delayed before being available through CloudWatch, or it might not be delivered at all."

The Execution Role

Every schedule's target names an IAM role, RoleArn, that Scheduler assumes to make the call. Its trust policy must allow scheduler.amazonaws.com, and AWS recommends conditions that tie it to your account and a schedule group (confused deputy prevention):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "scheduler.amazonaws.com" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012",
          "aws:SourceArn": "arn:aws:scheduler:us-east-1:123456789012:schedule-group/default"
        }
      }
    }
  ]
}

The permissions policy grants the target's API: lambda:InvokeFunction, states:StartExecution, or ecs:RunTask plus iam:PassRole for the task's execution and task roles (ECS), and sqs:SendMessage for the DLQ. KMS-encrypted targets also need kms:Decrypt and kms:GenerateDataKey (troubleshooting).

These mistakes fail every invocation while the schedule looks fine; TargetErrorCount climbs and the target never logs anything:

• The trust policy names events.amazonaws.com, the principal for rule roles such as ECS's ecsEventsRole. Scheduler can't assume it.
• aws:SourceArn names a schedule. AWS: "The ARN you specify must be a schedule group."
• The permission is on the function, not the role. A Lambda resource-based policy letting events.amazonaws.com invoke the function, the usual setup for a rule, grants nothing to Scheduler's role.
• The role can't pass the ECS task's roles, so RunTask is denied.

If TargetErrorCount climbs while the DLQ stays empty, AWS says that "likely indicates a permissions issue preventing EventBridge Scheduler from writing to the DLQ itself."

Why an EventBridge Schedule Didn't Run

Monitoring an EventBridge Scheduled Job

Alarms on TargetErrorCount, InvocationDroppedCount, or InvocationsSentToDeadLetterCount, plus the function's Errors, catch a failed invocation and a job that throws. Two failures move none of them:

• A schedule that stopped invoking. A disabled, deleted, or expired schedule makes no attempts and emits no errors. An alarm on InvocationAttemptCount that treats missing data as breaching can notice silence, but only per schedule group and only as reliably as best-effort metrics.
• A run that succeeded at nothing. A function that returns normally after exporting zero rows is a success to Lambda.

Both are the job of a dead man's switch: the job reports each run to a monitor outside AWS that knows the schedule, and a missing report is the alert.

Report Each Run to CronRadar Over HTTP

There is no CronRadar SDK for EventBridge Scheduler and no auto-discovery, and CronRadar's Python SDK isn't available right now, so each target reports with its own HTTP check-ins. This handler for the python3.14 runtime uses only the standard library:

# handler.py: the Lambda target of an EventBridge Scheduler schedule (python3.14).
import base64
import json
import os
import urllib.parse
import urllib.request

from orders_export import export_orders  # the job itself, deployed with this file

PING_URL = "https://cron.life/api/v1/ping/order-export"
SCHEDULE = "15 10 * * *"  # 06:15 New York is 10:15 UTC in summer, 11:15 in winter
GRACE_SECONDS = 4500  # the winter hour (3,600 s) plus 900 s of run time


def report(kind, run_id, message=None, outcomes=None):
    """Send one CronRadar check-in. Gives up after 5 seconds and never raises."""
    try:
        params = {"schedule": SCHEDULE, "gracePeriod": GRACE_SECONDS, "run_id": run_id}
        if message:
            params["message"] = message[:1000]
        query = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
        token = base64.b64encode(f"{os.environ['CRONRADAR_API_KEY']}:".encode()).decode()
        headers = {"Authorization": f"Basic {token}"}
        body = None
        if outcomes is not None:
            body = json.dumps({"outcomes": outcomes}).encode()
            headers["Content-Type"] = "application/json"
        request = urllib.request.Request(
            f"{PING_URL}/{kind}?{query}", data=body, headers=headers, method="POST"
        )
        with urllib.request.urlopen(request, timeout=5):
            pass
    except Exception as error:  # a monitoring problem must never fail the job
        print(f"CronRadar {kind} check-in failed: {error!r}")


def handler(event, context):
    run_id = context.aws_request_id  # Lambda keeps it when it retries this event
    report("start", run_id)
    try:
        rows = export_orders(event.get("scheduled_time"), context)
    except Exception as error:
        message = f"{type(error).__name__}; see CloudWatch Logs for request {run_id}"
        report("fail", run_id, message)
        raise
    report("complete", run_id, outcomes={"rows_exported": rows})
    return {"rows_exported": rows}

• Monitoring can't break the job. Each check-in gives up after 5 seconds (urllib applies the timeout to each blocking step, not the whole request), and its errors are logged and dropped. The job's exception is re-raised after fail, so Lambda still records and retries it. fail names only the exception type, since exception text can carry data that shouldn't leave your account.
• One run_id per event. Duplicate invocations "that have the same request ID indicate that the Lambda service retried the function" (re:Post). The handler can't tell which attempt is last, so a failed first attempt alerts at once and a successful retry records the recovery.
• A hang has to stop itself. At the function's timeout, at most 900 seconds (timeout), Lambda ends the run before fail is sent. CronRadar flags a run as stuck only when its start is still unanswered at the next expected run plus the grace period, and every check-in moves that deadline forward, so a job that times out nightly may never be flagged. Have export_orders check context.get_remaining_time_in_millis() between batches and raise when under a minute remains.
• Outcomes catch the empty run. Add the expectation rows_exported >= 1 in the monitor's settings, and a run that exports nothing opens an incident. Outcome values must be finite numbers or booleans, so export_orders returns an integer.
• The first check-in creates the monitor, and the next recreates it if deleted. schedule and gracePeriod apply only at creation; change an existing monitor in the dashboard.

In AWS SAM, a ScheduleV2 event creates the schedule, and an execution role when you omit RoleArn:

Transform: AWS::Serverless-2016-10-31
Resources:
  OrderExportFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: handler.handler
      Runtime: python3.14
      Timeout: 900
      Environment:
        Variables:
          CRONRADAR_API_KEY: '{{resolve:secretsmanager:cronradar/production:SecretString:api_key}}'
      Events:
        NightlyExport:
          Type: ScheduleV2
          Properties:
            Name: order-export
            ScheduleExpression: 'cron(15 6 * * ? *)'
            ScheduleExpressionTimezone: America/New_York
            FlexibleTimeWindow:
              Mode: 'OFF'
            Input: '{"scheduled_time": "<aws.scheduler.scheduled-time>"}'
            RetryPolicy:
              MaximumRetryAttempts: 10
              MaximumEventAgeInSeconds: 3600
            DeadLetterConfig:
              Type: SQS

The {{resolve:secretsmanager:...}} reference copies the key from Secrets Manager into the environment at deploy time. CloudFormation reads it only when it creates or updates the function, so a rotated key needs a redeploy, and the value "may show up in the service whose resource it's being used in": anyone who can view the function's environment variables can read it (dynamic references). To avoid that, or to use a Parameter Store SecureString (ssm-secure references don't work on Lambda functions), fetch it at run time with the Parameters and Secrets Lambda Extension and set CRONRADAR_API_KEY before the first check-in. An ECS task gets the variable from its task definition's secrets (ECS secrets). Use one CronRadar application and key per environment.

Convert the Schedule for CronRadar

CronRadar reads five-field cron in UTC, with Sunday as 0 and no year, ?, L, W, or #; when both day fields are restricted, a date must match both. Drop the year, replace ? with *, subtract one from numeric days of week, and convert local times to UTC. For a zone with daylight saving, use the earlier UTC time and a grace period of at least an hour plus the run time.

A rate() schedule's clock times depend on when it started, so replace it with the cron() it matches. L, W, 6L, and rates such as rate(10 days) have no five-field form: schedule the AWS side on every candidate date, let the job decide, and check in on every run, including early exits, which mustn't fail an outcome expectation. For the last day of the month, that's cron(0 23 28-31 * ? *) on AWS, 0 23 28-31 * * on CronRadar, and this check on the scheduled_time from the Input:

from datetime import datetime, timedelta


def is_last_day_of_month(scheduled_time):
    """scheduled_time is <aws.scheduler.scheduled-time>, such as 2026-10-31T23:00:00Z."""
    day = datetime.fromisoformat(scheduled_time).date()
    return (day + timedelta(days=1)).day == 1

For the last Friday, schedule every Friday and run when seven days later is in the next month; for 15W, schedule the 14th through 16th. Then invoke the function once, confirm order-export shows a success in the right CronRadar application, and let a scheduled run arrive.

Frequently Asked Questions

What is the cron format for EventBridge Scheduler?

Six fields inside cron(): minutes, hours, day-of-month, month, day-of-week, and year. One day field must be ?, day-of-week runs 1-7 from Sunday, and L, W, and # are supported. Daily at 02:30 is cron(30 2 * * ? *), in UTC unless the schedule sets ScheduleExpressionTimezone.

What is the difference between EventBridge Scheduler and EventBridge rules?

Scheduled rules are the legacy option: UTC only, recurring only, and 300 per event bus in most Regions. EventBridge Scheduler adds time zones, one-time schedules, flexible time windows, universal targets, and a default quota of 10 million schedules per Region. AWS recommends Scheduler.

Does EventBridge Scheduler retry failed invocations?

Yes, when the call to the target fails: up to 185 retries within at most 24 hours, with exponential backoff, then an optional SQS dead-letter queue. It doesn't retry the job's own failure: Lambda retries a function that throws, two more times by default, and an ECS task's non-zero exit is ECS's to report, not Scheduler's to retry.

Why didn't my EventBridge schedule run?

Check its state, dates, and time zone with aws scheduler get-schedule; an UpdateSchedule call resets every optional field it omits. Then check day-of-week numbering, where 2 is Monday, the daylight saving gap, and TargetErrorCount, which climbs when the execution role or target input is wrong.

How do I monitor a scheduled Lambda function?

Alarm on the function's Errors and Scheduler's TargetErrorCount, and have the function check in with a monitor outside AWS. With CronRadar, the handler reports start, complete, and fail over HTTP with a five-field UTC schedule, so a run that never happens alerts once its grace period passes.

This guide covers Functions runtime 4.x and the .NET isolated worker model (Microsoft.Azure.Functions.Worker.Extensions.Timer 4.3.1, current as of October 24, 2026). The trigger runs in the Functions host; source links below point to its code in azure-webjobs-sdk-extensions.

Isolated Worker or In-Process, and the Plans That Run Timers

Support for the in-process model ends on November 10, 2026. The in-process model runs .NET 8 at most, and Flex Consumption doesn't support it at all (model comparison), so every example here uses the isolated worker model. Migrating a timer function mostly means adding the Microsoft.Azure.Functions.Worker.Extensions.Timer package and replacing [FunctionName] with [Function].

Plan details from Microsoft's hosting comparison, checked October 24, 2026:

"Unbounded" still has edges: a running execution gets 60 minutes during scale-in on Flex Consumption and Premium, and 10 minutes during platform updates.

NCRONTAB Syntax

Functions parses schedules with the NCrontab library. The six fields are second (0-59), minute, hour, day of month, month (1-12 or Jan-Dec), and day of week (0-6 with Sunday as 0, or Sun-Sat):

*, ,, -, and / work as in standard cron, covered in cron expression syntax, and names are case-insensitive English (timer trigger reference). Two rules differ from Linux cron:

• Five fields are accepted too, and they mean something else. The runtime reads an expression with exactly five fields as minute-first cron and anything else as including seconds (CronSchedule.cs). Dropping one * from 0 */5 * * * * gives 0 */5 * * *: minute 0 of every fifth hour, not every five minutes, and no error.
• Both day fields must match. NCrontab finds a date matching the day of month, then checks the day of week (CrontabSchedule.cs), so 0 0 9 1-7 * Mon is the first Monday. Linux cron runs when either field matches.

TimeSpan Schedules

The schedule can also be a TimeSpan string such as 01:00:00, which Microsoft documents only for apps that run on an App Service plan (TimeSpan). It sets the interval between invocations rather than clock times, and when a run takes longer than the interval, the next one starts immediately. On Consumption and Flex Consumption, use NCRONTAB.

Schedules in App Settings

Wrap an app setting name in percent signs to keep the expression out of code: [TimerTrigger("%NightlyCleanupSchedule%")], with an app setting NightlyCleanupSchedule set to 0 0 2 * * *. If the setting doesn't exist, the host throws '%NightlyCleanupSchedule%' does not resolve to a value and the timer doesn't start (NameResolverExtensions.cs). Changing an app setting restarts the app (app settings).

Time Zones and Daylight Saving Time

Schedules run in UTC by default. For local time, add an app setting named WEBSITE_TIME_ZONE (NCRONTAB time zones):

• Windows, any plan: a Windows time zone name from tzutil.exe /L, such as Eastern Standard Time.
• Linux on Premium or Dedicated: a tz database name, such as America/New_York.
• Linux on Flex Consumption or Consumption: not supported. Microsoft warns that setting WEBSITE_TIME_ZONE or TZ there can cause SSL-related issues and stop your app's metrics.

With the setting in place, the schedule follows daylight saving time: 0 0 10 * * * on America/New_York fires at 10:00 local all year. On the night clocks go back, the extension skips the second occurrence of a repeated time, so a job at 01:30 runs once (CronSchedule.cs). The reference doesn't say what a job scheduled inside the skipped spring hour does, so keep daily jobs out of the hour around the change, or leave the app on UTC.

One Run at a Time: The Singleton Lease

The timer's listener is a singleton (TimerListener.cs): before an instance runs the schedule, it must hold a blob lease under locks/<host-id>/ in the azure-webjobs-hosts container of the AzureWebJobsStorage account, and other instances wait (BlobLeaseDistributedLockManager.cs). That's how "only a single instance of a timer-triggered function is run across all instances" (scale-out). It's also why timer triggers depend on blob storage everywhere except local Core Tools, and why an identity-based AzureWebJobsStorage connection needs the Storage Blob Data Owner role (connections).

The lease is keyed by host ID, and that's where it breaks:

• Two apps, one storage account, one host ID: only one timer runs (sharing storage). Outside Flex Consumption, the host ID defaults to the app name truncated to 32 characters, so contoso-billing-reconciliation-jobs-prod and contoso-billing-reconciliation-jobs-test collide. Runtime 4.x detects that case, logs AZFD0004, and stops the host (host ID considerations), but it checks only truncated default IDs (ScriptHostIdProvider.cs): two apps given the same explicit AzureFunctionsWebHost__hostid silently share one timer. Flex Consumption generates unique host IDs.
• A staging slot runs its own copy. With its own host ID it holds its own lease, so its timer fires alongside production's. Disable the function there with an AzureWebJobs.<FunctionName>.Disabled app setting marked as a deployment slot setting (disable in a slot).

Missed Runs: UseMonitor, ScheduleStatus, and IsPastDue

UseMonitor defaults to true for schedules that recur once a minute or less often, and to false for schedules that fire more than once a minute (attributes). With it on, the host stores a status blob at timers/<host-id>/<function>/status in azure-webjobs-hosts (StorageScheduleMonitor.cs) and passes it to the function in TimerInfo:

In the isolated worker, ScheduleStatus is null when UseMonitor is off (TimerInfo.cs). When the listener starts, it compares the stored Next with the clock (TimerListener.cs, ScheduleMonitor.cs):

• If Next has passed, it runs the function once, immediately, with IsPastDue set. That's one catch-up run however many occurrences were missed: a daily job whose app was down from Friday night to Monday morning runs once on Monday.
• If the schedule expression changed, the stored status is reset and there is no catch-up run.
• With UseMonitor off, missed occurrences are skipped without a trace.

The status is written only after an invocation returns. If the host process dies mid-run, that occurrence stays unrecorded, and the next listener start treats it as past due and runs it again. Together with slots and retries, that's why Microsoft recommends designing functions for identical input: a timer job should be safe to run twice.

RunOnStartup

RunOnStartup = true invokes the function whenever the runtime starts: when the app wakes from idle, restarts after a change, or scales out. Microsoft says it "should rarely if ever be set to true, especially in production," because it runs code at unpredictable times, and on the Consumption plan the extra invocations on every scale event can raise costs significantly (attributes and caution). To run a job once after a deployment, invoke it manually instead.

Timeouts, Retries, and Overlapping Runs

Timeouts. functionTimeout in host.json (for example "functionTimeout": "00:45:00") caps each execution; the defaults are in the plan table. When an execution exceeds it, the runtime logs a timeout error and restarts the language worker process (timeout duration), ending any work in flight.

Retries. By default a failed timer run isn't retried; the next attempt is the next occurrence (retry behavior). Timer triggers do support function-level retry policies, [FixedDelayRetry] and [ExponentialBackoffRetry], in the isolated worker with Microsoft.Azure.Functions.Worker.Extensions.Timer 4.2.0 or later. The retry count lives in the instance's memory and a timer retry doesn't resume on another instance, so you can get fewer retries than you asked for (retry policies).

Overlap. A timer never overlaps itself within one app: it "will not trigger again if there is an outstanding invocation still running" (scale-out). The listener computes the next occurrence from the time a run started and arms the timer only after the run returns (TimerListener.cs). An every-five-minutes job that runs from 10:00 to 10:12 runs again at 10:12, immediately and without IsPastDue, then at 10:15. The 10:05 and 10:10 occurrences collapse into that one late run.

Why an Azure Functions Timer Trigger Isn't Firing

Alerting When a Timer Run Fails or Never Starts

Application Insights records each invocation in the requests table, so an alert on failed requests catches runs that throw or time out. A run that never starts writes nothing for that alert to fire on. A log search alert can fire when a function's request count drops to zero, but each query has to encode its function's schedule, and Microsoft notes that log search alerts "work best when you're trying to detect specific data in the logs, as opposed to when you're trying to detect a lack of data" (alert types).

The pattern built for absence is a dead man's switch: the function checks in on every run, and a service outside Azure that knows the schedule alerts when a check-in is late.

Add CronRadar to an Isolated Worker Timer Function

Azure Functions has no CronRadar auto-discovery; each timer function reports through the base CronRadar .NET SDK. NuGet installs CronRadar 1.0.13 (checked October 24, 2026):

dotnet add package CronRadar

Create one CronRadar application per environment and put its API key in an app setting named CRONRADAR_API_KEY; app settings reach your code as environment variables, where the SDK reads it. A Key Vault reference keeps the key out of the app's configuration, as long as the app's managed identity can read the secret:

az functionapp config appsettings set \
  --name contoso-maintenance --resource-group contoso-prod \
  --settings "CRONRADAR_API_KEY=@Microsoft.KeyVault(SecretUri=https://contoso-prod-kv.vault.azure.net/secrets/cronradar-api-key)"

For local runs, put a development application's key in local.settings.json under Values. Then wrap the job:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Contoso.Maintenance;

// Your service that does the cleanup; register an implementation in Program.cs.
public interface ISessionCleanup
{
    Task DeleteExpiredAsync(CancellationToken cancellationToken);
}

public class NightlyCleanup(ISessionCleanup cleanup, ILogger<NightlyCleanup> logger)
{
    [Function(nameof(NightlyCleanup))]
    public async Task Run(
        [TimerTrigger("0 0 2 * * *")] TimerInfo timer, // 02:00:00 UTC every day
        CancellationToken cancellationToken)
    {
        if (timer.IsPastDue)
        {
            logger.LogWarning("Catch-up run for a missed occurrence. Last recorded run: {Last}",
                timer.ScheduleStatus?.Last);
        }

        // The class shares its namespace's name, so qualify it fully.
        await CronRadar.CronRadar.WrapAsync("nightly-cleanup", async () =>
        {
            // Give up well before functionTimeout so a hang becomes a reported failure.
            using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
            deadline.CancelAfter(TimeSpan.FromMinutes(20));
            await cleanup.DeleteExpiredAsync(deadline.Token);
        }, schedule: "0 2 * * *");
    }
}

The wrapper sends start before the work and complete after it returns. If the work throws, it sends fail with the exception message and rethrows the original exception, so Functions still records the failed invocation and a retry policy still sees it. Each check-in times out after 5 seconds and never throws: if cron.life is unreachable, the run takes up to about ten seconds longer and its result doesn't change. The schedule argument creates the monitor on the first run and recreates it if it's ever deleted.

The 20-minute deadline matters because of how CronRadar detects stuck runs. Every check-in, start included, moves the expected time to the next scheduled occurrence; if that time plus the grace period passes while the last event is a start, the monitor goes critical as stuck. A run cut off by functionTimeout may never send its fail, because the worker process restarts, and the next night's start resets the window, so a job that timed out every night might never be flagged as stuck. A deadline shorter than functionTimeout turns the hang into a fail that alerts immediately, as long as the work honors the token. On Consumption, with its 5-minute default, set it lower. A host shutdown cancels the same token and is reported as a failure too.

With a retry policy, each attempt is a separate invocation, so the first failed attempt alerts even if a retry succeeds; the retry's complete then records the recovery.

Convert the Schedule for CronRadar

CronRadar reads five-field cron in UTC. Drop the seconds field and convert local times:

A five-field Functions schedule passes through unchanged if the app runs in UTC. Work that must run more than once a minute fits better in a long-running process; see scheduled tasks with BackgroundService.

For a WEBSITE_TIME_ZONE schedule that follows daylight saving time, use the earlier of the two UTC times and a grace period of at least an hour plus the job's usual duration. 10:00 in New York is 14:00 UTC in summer and 15:00 UTC in winter, so send 0 14 * * *. WrapAsync takes no grace period, and DefaultGracePeriodSeconds has no effect here: the start check-in carries only the schedule, and CronRadar creates the monitor with its 90-second default. Set the grace period in the CronRadar dashboard (Grace Period, in seconds), either by creating the monitor before the first run or by editing the one the first run creates.

In winter the monitor then shows warning for the hour before each run. Leaving the app on UTC avoids the whole problem.

Run the function once from the portal, confirm nightly-cleanup shows a success result in the right CronRadar application, then let one scheduled run arrive. The .NET monitoring overview covers other .NET schedulers.

Frequently Asked Questions

What cron format does an Azure Functions timer trigger use?

NCRONTAB, with six fields and seconds first, so daily at 02:00 is 0 0 2 * * *. A five-field expression is also accepted and read as standard minute-first cron. On an App Service plan, the schedule can instead be a TimeSpan interval such as 01:00:00.

How do I set the time zone for an Azure Functions timer?

Add a WEBSITE_TIME_ZONE app setting: a Windows time zone name on Windows, or a tz database name such as America/New_York on Linux Premium and Dedicated. Flex Consumption and Linux Consumption don't support it, so write those schedules in UTC.

Why didn't my Azure Functions timer trigger run?

Usually an idle Dedicated app without Always On, triggers not synced after deployment, a disabled function, unreachable host storage, a host ID collision, or a schedule in an unexpected zone. If the host was down at the scheduled time, UseMonitor makes up one run at startup; without it, the run is skipped.

Can a timer-triggered function run twice at the same time?

Not within one function app: a blob lease keeps the timer on one instance, and it won't fire while the previous run is still going. Duplicates come from outside that lease: a staging slot, two apps with different host IDs running the same code, RunOnStartup, or a past-due rerun after the host died mid-run.

How do I get alerted when a timer function doesn't run?

Have the function check in with a monitor outside Azure on every run. With CronRadar, wrap the job in CronRadar.CronRadar.WrapAsync with the five-field UTC schedule: a missing check-in raises an alert after the grace period, and an exception raises one immediately.

This guide covers BullMQ 6.4.2, the latest release on npm (checked October 25, 2026), with notes for the still-maintained 5.x line. For in-process schedulers such as node-cron, see Node.js cron job monitoring. To see how BullMQ compares with Agenda and the in-process libraries, see Node.js schedulers compared.

How a Job Scheduler Produces Each Run

BullMQ 6 no longer installs ioredis for you; it is an optional peer dependency that Redis users install explicitly:

npm install bullmq ioredis

import { Queue } from 'bullmq'

const queue = new Queue('reports', { connection: { host: '127.0.0.1', port: 6379 } })

// Every day at 02:30 UTC. Calling this again with the same ID updates it.
await queue.upsertJobScheduler(
  'nightly-invoice-export',
  { pattern: '30 2 * * *', tz: 'UTC' },
  { name: 'invoice-export', data: { format: 'csv' }, opts: { attempts: 3 } },
)

The call returns the first job, in the delayed state. From then on, per the Job Schedulers guide, there is always one delayed job for the scheduler, and "the scheduler will only generate new jobs when the last job begins processing." The worker that picks up a run creates the next one (worker.ts), so a busy queue delays later runs. Each run gets the ID repeat:<scheduler id>:<timestamp>; you cannot set a custom job ID.

Pattern Syntax and Time Zones

Patterns are parsed by cron-parser (BullMQ 6.4.2 depends on cron-parser 5.10.2). Five fields work as in crontab, and an optional sixth field at the front is seconds: the repeat strategies page writes 09:00 on weekdays as 0 0 9 * * 1-5. cron-parser also accepts L, #, ?, H, 7 for Sunday, and shortcuts such as @daily.

Set tz explicitly. Without it, cron-parser builds dates in the local zone of the process doing the calculation (CronDate.ts), and that is the producer for the first run and each worker after that. A fleet with mixed TZ settings computes different run times. BullMQ 6 removed the old utc option; use tz: 'UTC'.

Intervals, Immediate Runs, and Limits

• every takes milliseconds and can't be combined with pattern. A new every scheduler runs its first job immediately (the immediately flag was deprecated for this in 5.19.0), and in 6.4.2 later runs are spaced from that first run rather than aligned to the clock (getJobSchedulerEveryNextMillis.lua), although the repeat options page still describes clock alignment.
• immediately: true on a pattern scheduler makes the next run happen now. Left in startup code, it adds an off-schedule run every time the upsert executes (job-scheduler.ts).
• startDate, endDate, and limit bound the schedule; past endDate or limit, no more jobs are produced.

Repeatable Jobs Are Gone in BullMQ 6

BullMQ 6 removed Queue.add(..., { repeat }), addBulk with repeat, the Repeat class, getRepeatableJobs(), removeRepeatable(), and removeRepeatableByKey() (migration guide). Legacy repeatable data left in Redis is not converted. When a 6.x worker picks up a job from a legacy repeatable, it runs that job, emits an error event that begins "Failed to add repeatable job for next iteration", and schedules nothing after it (worker.ts). Without an error listener, the schedule ends quietly after one more run.