Cron expression generator and explainer

A standard cron expression has five fields separated by spaces: minute (0 to 59), hour (0 to 23), day of the month (1 to 31), month (1 to 12, or JAN to DEC) and day of the week. Each field takes a single value, a list such as 1,15, a range such as 9-17, an asterisk for every value, or a step such as */15. A step counts through the range it follows, so 0-30/10 means minutes 0, 10, 20 and 30.

Steps restart at the start of each larger unit rather than counting continuously. */7 in the minute field runs at 0, 7, 14 and so on to 56, then at 0 again: the last gap of each hour is 4 minutes, not 7. */5 in the hour field runs at 0, 5, 10, 15 and 20, leaving 4 hours between 20:00 and midnight. If you need an exact interval that does not divide the hour or the day, cron is the wrong tool and a fixed-rate timer is better.

Days that do not exist are skipped, never moved. 0 0 31 * * runs in only seven months a year, and 0 0 30 2 * never runs at all. The generator lists the next runs, so a schedule that runs rarely or never shows up immediately instead of in production.

Day-of-week numbering is the most common trap. In Unix cron and Spring, 0 and 7 are both Sunday, so 1 is Monday. In Quartz, 1 is Sunday and 7 is Saturday, so 2-6 means Monday to Friday. An expression copied from a Quartz job into Spring therefore shifts every day by one. Names such as MON-FRI mean the same everywhere, so use them where the dialect allows. Kubernetes accepts only 0 to 6 and rejects 7.

The two day fields combine differently. In Unix cron, if both day-of-month and day-of-week are restricted, a day that matches either one runs: 0 9 13 * 5 runs on every 13th and on every Friday, not only on Friday the 13th. cronie and Vixie cron treat a field that starts with an asterisk as unrestricted, so */2 in day-of-month switches back to requiring both. Kubernetes, which parses schedules with the robfig/cron library, treats */2 as restricted. Spring always requires both fields to match, and Quartz refuses to set both at all: one of them must be a question mark.

Quartz and Spring add a seconds field at the start, which is why a five-field expression pasted into them fails, and a six-field one pasted into a crontab is read with the seconds as minutes. They also support L for the last day of the month, W for the nearest weekday and # for the nth weekday, such as 6#3 for the third Friday in Quartz. None of these exist in Unix cron, GitHub Actions or Kubernetes.

A cron expression has no time zone of its own. Unix cron reads it in the server's zone, or the zone in CRON_TZ on cronie. Quartz and Spring use the JVM default unless you pass one. GitHub Actions uses UTC unless the schedule sets timezone. Kubernetes uses the kube-controller-manager's zone unless the CronJob sets spec.timeZone, which has been stable since Kubernetes 1.27; putting CRON_TZ or TZ inside the schedule is rejected with a validation error.

In a zone with daylight saving, one night a year skips an hour and another repeats one. cron(8) documents what cronie does: a job at a fixed time in the skipped hour runs immediately after the change, a fixed-time job is not run twice in the repeated hour, and jobs that run every hour or more often are scheduled normally. GitHub documents that a run in a skipped hour advances to the next valid time, so 02:30 becomes 03:00. Quartz only warns that the change can cause a skip or a repeat, and the Spring and Kubernetes docs do not say. The run list here flags every affected run with what the docs say.

The safest schedule avoids the change window entirely: in Europe and North America the changes happen between 01:00 and 03:00 local time, so a nightly job at 04:00 or in UTC never meets one.

Treat the schedule and the job as two things to test separately. The schedule is pure date arithmetic: assert that the expression produces the expected next run times from a fixed starting point, including a case that crosses a daylight saving change and one at a month end. Spring's CronExpression.next and Quartz's getNextValidTimeAfter run in milliseconds, and the JSON export here gives you the expected values.

Test the job by triggering it directly. Kubernetes can create a one-off Job from a CronJob's template with kubectl create job --from=cronjob/<name>. GitHub Actions workflows can add workflow_dispatch so the same workflow runs from a button. For Unix cron, run the command with cron's minimal environment, because a job that works in your terminal and fails from cron almost always depends on PATH or a variable set by your shell profile.

Then check what happens around the run: what the job does if the previous run is still going, if the machine was off at the scheduled time, and whether it is safe to run twice. Those are the failures that reach production, and none of them depend on waiting for the clock.

GitHub Actions runs scheduled workflows only from the default branch, no more often than every 5 minutes, and does not support macros such as @daily. GitHub warns that scheduled runs can be delayed at busy times, especially at the start of every hour, and that queued runs may be dropped under high load. A minute such as 17 rather than 0 makes delays less likely. In a public repository, scheduled workflows are disabled after 60 days with no repository activity.

A Kubernetes CronJob creates a Job for each scheduled time. concurrencyPolicy decides what happens if the previous Job is still running: Allow (the default) runs both, Forbid skips the new run and Replace stops the old one. startingDeadlineSeconds sets how late a missed run may still start. If the controller finds more than 100 missed schedules since the last run, it does not start the Job and logs an error, which is a reason to set startingDeadlineSeconds on any CronJob that runs often.