Schedules, clock changes, missed runs
How schedules run
On this page
This page says what the scheduler does today.
This page as Markdown: /docs/run-semantics.md.
Schedules
A schedule is a five-field cron expression (minute, hour, day of month, month, day of week), read as Vixie cron reads it: lists, ranges and steps, month and weekday names, and both 0 and 7 for Sunday.
When both day fields are restricted, a day matches when either of them does.
Each schedule is read in its own IANA time zone, not in the server's.
Other dialects are refused by name, each with what to write instead: a CRON_TZ= or TZ= prefix (the time zone is a field of its own), six or seven fields (a seconds or a year field), and RRULEs.
Clock changes
When the clocks go back, a schedule whose hour field starts with * (every hour, or a step such as */2) runs at both passes of each repeated wall time it matches.
A schedule with a literal hour, list or range runs a repeated wall time once, at its first pass.
When the clocks go forward, a wall time they skip runs once, at the moment they go forward.
Runs that land on the same instant are one run.
When a run starts
A scheduled run is queued only once its scheduled minute has come, and it starts after that minute, never before it.
A run can start later under load. Queued runs start one after another; when a tick has used its start budget, or a run's worst case no longer fits in what is left of the request, the run stays queued and a later tick starts it.
A run executes the workflow as it is saved when the run starts, not when it was queued, and records the revision it was queued with.
A paused or deleted workflow's schedule queues no runs.
At most once
Each scheduled time gets at most one run: a second tick at the same time queues nothing more.
Each run executes at most once: two attempts to execute one queued run execute it once.
A run still running 6 minutes after it started, because the request executing it ended, is failed by a later tick with the error "Run did not finish" and is not run again.
Failures
A run whose delivery fails is recorded as failed, with the delivery's error, even when its steps succeeded: its outcome is then ok and its deliveryStatus is failed.
Failed runs in a row pause the schedule when they reach the threshold the deployment sets, and the paused schedule queues no runs.
Missed times and overlap
When the tick reaches a schedule late, the newest of the scheduled times it finds runs, and each time before it is recorded as missed, with the reason. When more than 100 were missed, the newest 100 each have a record and one record stands for the rest.
A scheduled time that comes while an earlier run of the same schedule is queued, running or still delivering does not run: it is recorded as skipped, with the reason.