How to Debug a Cron Job That Silently Skips Its DST Run

Description and use

A cron job fails during DST transitions. The fix involves confirming local time usage, adding idempotency, avoiding the 1‑3 AM window, and testing transition dates.

Problem

A cron job scheduled at 2:30 AM local time runs reliably most of the year but twice a year either skips or runs twice due to daylight‑saving‑time transitions.

Outcome

The job now runs once per day, with idempotent safeguards, clear documentation, and automated tests ensuring correct behavior across DST transitions.

Workflow

• Confirm cron interprets schedules in local time, not UTC.
• Identify whether the issue occurs during spring‑forward or fall‑back by checking logs and DST transition dates.
• Read the scheduler’s documentation on DST behavior to understand its default handling.
• Add idempotency to the job to guard against duplicate runs during fall‑back.
• Avoid scheduling critical jobs inside the 1:00‑3:00 AM window; move them to a safer time like 5:00 AM.
• Write regression tests that simulate the transition dates and assert exactly one run.
• Document the chosen behavior next to the cron configuration for future engineers.

Evidence

A recurring job scheduled for 2:30 AM local time runs reliably for months, then twice a year it either doesn't run at all or runs twice back to back.

Source

Spring-forward (an hour skips, e.g., 2:00 AM jumps straight to 3:00 AM) and fall-back (an hour repeats, 1:00-2:00 AM happens twice) produce different symptoms.

Source