CronCraft

CronCraft / Guide

Cron, time zones and the two hours that break schedules

A cron expression has no time zone. It reads a wall clock, and twice a year some wall clocks jump. This guide shows where the zone comes from, what the two failures look like, and how to design around them.

The expression is not the schedule

People read 0 2 * * * as "two in the morning" and stop there. The scheduler reads it as "when the local clock shows 02:00". The local clock belongs to the process or the platform, not to the expression. That gap is where most time zone incidents begin.

Move the same job from a Seoul server to a UTC container and it runs at 11:00 Seoul time. Copy the expression from a laptop in Berlin to a GitHub Actions workflow and it runs at 02:00 UTC, which is 04:00 in Berlin in summer. Nothing in the expression changed because the expression never contained the zone.

Where each platform gets its zone

PlatformZone usedHow to control it
Unix cron, cronieDaemon or server local timeCRON_TZ at the top of the crontab where supported, otherwise change the server zone
QuartzJVM default time zone unless configuredSet the scheduler time zone explicitly in code or configuration
AWS EventBridge SchedulerUTCConvert the intended local time to UTC
GitHub ActionsUTCNo option; convert to UTC
Kubernetes CronJob.spec.timeZone, else controller local timeSet timeZone on clusters that support it
systemd timerHost time zoneSet the host zone or use UTC expressions with a UTC host

Run infrastructure in UTC

UTC has no daylight saving and no political offset changes in the usual cases, so a schedule written in UTC is stable. This is the default recommendation for backups, rotations, sync jobs and anything whose correct behavior does not depend on a human being awake. Convert to local time only for display, reports and business hours logic inside the job.

Business schedules are the opposite case. "Every weekday at 09:00 local" must follow the local clock, including its daylight saving changes. Pick the local zone explicitly and accept that the UTC instant moves twice a year, or accept that 09:00 local becomes 08:00 or 10:00 for part of the year.

Spring forward: the hour that does not exist

In America/New_York, on 14 March 2027, the clock goes from 01:59:59 to 03:00:00. Every wall clock time from 02:00 to 02:59 is skipped. A job at 30 2 * * * has no 02:30 that day.

What a daemon does next is implementation specific:

  • Some skip the run entirely.
  • Some notice the clock jump and run missed jobs once when the clock lands, so the backup runs at 03:00.
  • Some have a policy flag for exactly this case.

For a daily job this is usually a one day inconvenience. For a job that must run once and only once per day, the skip is a correctness problem. The safe pattern is to schedule outside the transition window, or to make the job check the date and repair a missing run later.

Fall back: the hour that happens twice

In America/New_York, on 7 November 2027, the clock goes from 01:59:59 back to 01:00:00. Every wall clock time from 01:00 to 01:59 occurs twice, once at UTC-4 and once at UTC-5. A job at 30 1 * * * has two valid instants that day.

Some schedulers deliberately avoid the duplicate. Others do not. If the job sends an email, charges a card or rotates a credential, a second run can be visible to users. The usual engineering answer is idempotency: a unique key per logical run, a lock, or a check that the work is already done.

The timezone board in CronCraft shows both instants with their offsets, so you can see the duplicate before it reaches production. The DST card counts how many of your scheduled wall clock minutes fall inside the repeated hour.

Half hour and 45 minute zones

Not every offset is a whole hour. Asia/Kolkata is UTC+05:30, Asia/Kathmandu is UTC+05:45, and Australia/Lord_Howe uses a 30 minute daylight saving shift. A fixed offset assumption in a test will pass for London and fail for Kathmandu. The timezone board resolves real offsets through the browser's IANA data, including these zones and their historical rules.

How to test a schedule across a transition

  1. Set the primary zone to the zone that actually runs the job, not your own.
  2. Pick a starting moment a few days before the transition and compute the next 20 runs.
  3. Read the dates. A daily 02:30 job should show 02:30 on every date except the spring forward date.
  4. For the fall back, look for two rows with the same wall clock time and different offsets.
  5. Repeat for both transitions in the year, because the dates differ by zone.

This is exactly what the timezone tab does, and it takes less time than reading a tz database changelog. The scan covers 365 days so both transitions are included no matter when you run it.

Design rules that survive the clock change

  • Choose one zone per job and write it down next to the schedule.
  • Prefer UTC for infrastructure, local zone for human facing schedules.
  • Avoid the 01:00 to 03:00 local window for jobs that must run exactly once.
  • Make every job idempotent, then a duplicate run is boring instead of an incident.
  • Test the next runs across both transitions before the first deploy, and again when a platform changes its default.