CronCraft

CronCraft / Guide

Cron dialects, compared field by field

The five column cron line is a shared idea, not a shared specification. This is what changes when the expression moves between Unix cron, Quartz, AWS EventBridge, GitHub Actions, Kubernetes and systemd.

Why the same expression behaves differently

Cron began as a Unix daemon with five fields. Every ecosystem that needed scheduled work copied the idea and changed something: added seconds, added a year, added a question mark for "not applicable", or fixed the time zone to UTC. The result looks familiar and behaves differently. Most migration bugs are not logic bugs; they are field order bugs and time zone bugs.

The studio has a dialect selector for the three field orders. GitHub Actions and Kubernetes use the Unix order and differ mainly in where the schedule runs, which is covered in the time zone guide.

DialectField orderSpecial charactersTime zone
Unix cron, cronie, Vixieminute hour day month weekdayranges, lists, steps, names, macrosServer local time, CRON_TZ where supported
Quartz and Springsecond minute hour day month weekday [year]? L W #JVM or scheduler default
AWS EventBridgeminute hour day month weekday year? L W #UTC
GitHub Actionsminute hour day month weekdaynoneUTC
Kubernetes CronJobminute hour day month weekdaynone.spec.timeZone, else controller time
systemd timerOnCalendar expressioncalendar syntax, not cronHost time zone

Unix cron, cronie and Vixie cron

Field order: minute, hour, day of month, month, day of week. Ranges, lists, steps, month and weekday names, and the macros @hourly, @daily, @weekly, @monthly and @yearly are the common core. Sunday is 0, and most implementations also accept 7.

The behavior that surprises people is the day rule: when both day-of-month and day-of-week are restricted, a timestamp matches if either matches. This is not accidental. It comes from the original implementation and scripts rely on it. 0 0 13 * 5 means the thirteenth of the month or any Friday, not Friday the thirteenth.

Classic Unix cron has no L, W or #. Last day of month is usually done by running on 28 through 31 and exiting unless tomorrow is the first. Some distributions patch in CRON_TZ; assume nothing until you check the man page of the daemon you actually run.

Quartz and Spring

Field order: second, minute, hour, day of month, month, day of week, and optionally year. The seconds field is the first difference. A five field expression pasted into a Quartz scheduler is read with a missing field or a shifted meaning, depending on the library.

Quartz adds four ideas:

  • ? means "no specific value" and is used in exactly one of day-of-month or day-of-week. It is not the same as * conceptually, although it often behaves like it.
  • L in day-of-month means the last day of the month. In day-of-week, 6L means the last Friday, because Quartz counts Sunday as 1 and Saturday as 7.
  • W means the nearest weekday to a given day. 15W is the weekday nearest the fifteenth, without crossing into another month.
  • # means the nth weekday. 2#2 is the second Monday, because Quartz numbers Sunday as 1.

Quartz also chooses between OR and AND day matching through a calendar setting, but the common default still behaves like Unix for many users. Treat day semantics as something to verify in your own configuration rather than assuming a portable rule.

AWS EventBridge

Field order: minute, hour, day of month, month, day of week, year. The year is last, not first. EventBridge Scheduler runs in UTC, supports ?, L, W and #, and does not have a seconds field. A Quartz expression with seconds first will be read as a completely different schedule, and an expression with six fields in the Unix order is missing the year.

The studio's EventBridge mode expects six fields with the year last and rejects a Quartz style seconds expression with a field count error, which is the quickest way to catch a copy paste from a Spring project.

GitHub Actions

Field order: the Unix five. Schedules run in UTC, ignore repository or runner time zones, and are not guaranteed to start exactly on the minute during periods of high load. The shortest practical interval is five minutes. A seconds field is not supported.

If the business requirement is 09:00 in Seoul, write 0 0 * * 1-5 and accept that the local clock will read 09:00 all year because Seoul has no daylight saving. For a zone with daylight saving, the local time of a fixed UTC schedule moves by an hour twice a year. That is a product decision, not a cron bug.

Kubernetes CronJob

Field order: the Unix five. Current clusters accept .spec.timeZone with an IANA name. Without it, the controller manager's local time is used, which is usually UTC in managed clusters. Two other fields matter for production:

  • concurrencyPolicy: Forbid prevents a new run while the previous one is still going, which is the simplest protection against overlap.
  • startingDeadlineSeconds controls how late a missed run may start. The default can produce surprising catch up behavior after a controller outage.

systemd timers

systemd is not cron. OnCalendar uses a calendar expression such as Mon..Fri *-*-* 09:00:00, and the timer runs in the host time zone. The exporter in this app translates the common fields, including minute and hour steps and the ~01 form for the last day of the month, and leaves a comment when a rule has no direct equivalent. Persistent=true runs a missed job after downtime, which may or may not be what you want.

Migration checklist

  • Count the fields before reading them. Five or six is the first question, not the last.
  • Check which end the extra field is on: seconds at the front in Quartz, year at the end in EventBridge.
  • Decide what happens to the day rule. If both day fields are restricted, confirm OR or AND in the target system.
  • Find the time zone the runner actually uses and convert the expression or set the zone explicitly.
  • Read the next five executions in the target zone, not in the zone you are sitting in.
  • Export from one source instead of copying an expression between tools by hand.