Recurrence Edge Cases
Basic recurrence is easy. Production recurrence is hard. rrule.net is battle-tested against DST boundaries, leap years, bounded rules, timezone shifts, and long-running schedules.
What breaks simple schedulers
- Daylight Saving Time transitions (UTC offset changes)
- Leap years and variable month lengths
- Finite recurrences (
COUNT/UNTIL) - Old high-frequency schedules resumed long after creation
- Wall-clock invariants across timezones
Local clock or elapsed time?
Calendar rules, including RRule and cron inputs, follow the local clock. During an autumn overlap, a repeated local time selects its first passage. For example, 02:30 in Europe/Paris on October 25, 2026 selects 00:30 UTC; it does not also run at 01:30 UTC.
An elapsed cadence uses an exact starting instant and a fixed duration. It continues through both passages and preserves its original phase when resumed. Use native recurrence JSON with temporalVersion: 2 to request this behavior:
{
"recurrence": {
"temporalVersion": 2,
"kind": "input",
"start": "2026-10-25T00:00:00Z",
"tzid": "Europe/Paris",
"include": [
{
"elapsed": {
"start": "2026-10-25T00:00:00Z",
"every": "PT600S",
"tzid": "Europe/Paris",
"count": 13
}
}
],
"exclude": []
},
"count": 13
}Replace the example start with your intended anchor. A bare natural-language request such as "every minute" requires clarification between local-clock and elapsed semantics. Hosted targets must leave at least 60 seconds between consecutive occurrences. See the API reference for the versioned JSON contract.
Challenge scenarios
Pick a scenario, run it in your own scheduler, and compare behavior. All examples below are generated relative to the current date to avoid stale test data.
dst
Weekly at 09:00 America/New_York across DST
Wall-clock time should stay at 09:00 local while UTC timestamps shift at DST boundaries.
Input
{
"endpoint": "POST /v1/schedules/simulate",
"payload": {
"input": "Every Sunday at 9am",
"timezone": "America/New_York",
"count": 20
}
}Expected behavior
{
"expectation": "Occurrences stay on Sunday 09:00 local time, with UTC offsets changing when DST changes."
}How to use this guide
- Use
validateandsimulateto confirm recurrence logic. - Create a real schedule with a test endpoint (webhook.site or ntfy.sh).
- Verify execution history and payload shape.
- Ensure your consumer deduplicates rare recovery redeliveries.
If your system passes these scenarios consistently, you are much closer to production-grade recurrence handling.