Your calendar app is probably wrong right now. Not broken — just wrong. There’s almost certainly a scheduled event somewhere in your calendar whose “correct” local time depends on which of several competing definitions of “correct” you’re using, and your calendar app silently picked one.
This is the nature of timezone math. It looks simple. It is not simple. Here’s a tour of why.
The basics you know
Timezones divide the world into regions that share a UTC offset. America/New_York is UTC-5 in winter, UTC-4 in summer. Asia/Tokyo is UTC+9, always. Converting between them is arithmetic.
This is the model most developers have. It works for most cases. It breaks badly for the rest.
Daylight Saving Time
DST is the first landmine. Clocks in most US states “spring forward” one hour in March and “fall back” in November. The exact transition time is 2:00 AM local time. This produces two problems:
The missing hour. On the second Sunday in March, clocks move from 1:59 AM directly to 3:00 AM. The entire hour between 2:00 AM and 3:00 AM does not exist. If you schedule a job for 2:30 AM on that day, what happens? Different systems make different choices: skip it, run it at 3:30 AM, run it twice. There’s no objectively correct answer — there’s only the answer your system documented (or didn’t).
The ambiguous hour. On the first Sunday in November, clocks move from 1:59 AM back to 1:00 AM. The hour between 1:00 AM and 2:00 AM happens twice. A timestamp of 2026-11-01T01:30:00 in America/New_York is ambiguous — it could be during EDT (before the transition) or EST (after it). If you’re logging events, these two timestamps are indistinguishable without an explicit offset.
The correct representation is ISO 8601 with offset: 2026-11-01T01:30:00-04:00 (EDT) or 2026-11-01T01:30:00-05:00 (EST). When Microwave returns a datetime for a timezone-sensitive result, we always include the offset. This is not optional. Ambiguous datetimes are bugs waiting to happen.
DST rules change
The US changed its DST rules in 2007. Before the Energy Policy Act of 2005 took effect, DST started on the first Sunday of April and ended on the last Sunday of October. After 2007, it starts on the second Sunday of March and ends on the first Sunday of November.
This means any historical datetime conversion that spans the pre-2007 period uses different rules than today. If you’re converting a timestamp from March 2006 in an Eastern timezone, the offset is different from the same date in 2008.
Most systems handle this correctly — they use the IANA timezone database, which maintains historical rules for every timezone. But if you’re rolling your own timezone math using a simple UTC offset table, you’ll get wrong answers for historical dates.
Political timezone changes
Here’s where it gets genuinely strange.
On December 29, 2011, Samoa ceased to exist. Not the country — just that day. Samoa had been on the American side of the International Date Line (UTC-11) for most of its history, a legacy of trade ties with the US. But its primary trading partners had shifted to Australia and New Zealand. So the government announced that December 30, 2011 would not occur in Samoa. The country jumped from December 29 directly to December 31, crossing the date line and moving to UTC+13.
If you have a Samoan timestamp from December 30, 2011, it is — in a very literal sense — invalid. The correct handling is to map it to December 31 and document that you’ve done so.
Samoa is a particularly dramatic example, but timezone changes happen regularly. Countries shift offsets for political reasons, daylight saving time rules are added or removed, regions are reassigned between timezone definitions. The IANA database tracks all of this. If your system doesn’t pull from the IANA database, it’s accumulating error over time.
The IANA timezone database
The IANA (Internet Assigned Numbers Authority) maintains the definitive database of timezone rules, historical changes, and future transitions. It’s updated multiple times per year as governments announce changes. The identifiers look like America/New_York, Asia/Kolkata, Pacific/Apia (Samoa).
If you’re using timezone identifiers in your code and they don’t come from the IANA database, you’re using something unofficial. “EST” is not an IANA identifier — it’s an abbreviation that maps to multiple different timezone rules depending on context. America/New_York is unambiguous.
Microwave accepts and returns IANA timezone identifiers exclusively. We don’t accept “EST” or “Pacific Time.” We run on a regularly updated copy of the IANA database and push updates within 24 hours of a database release.
What we handle
- All historical DST transitions in the IANA database
- Ambiguous local times during fall-back transitions (we return the pre-transition offset by default, document the ambiguity, and accept an explicit
dst_beforeparameter for the other interpretation) - Non-existent local times during spring-forward transitions (we advance to the post-gap equivalent and return the actual datetime)
- Political timezone changes and reassignments
- Half-hour and quarter-hour offsets (India is UTC+5:30, Nepal is UTC+5:45, Chatham Islands are UTC+12:45 or UTC+13:45)
- Negative DST (Lord Howe Island shifts by only 30 minutes for DST)
What we explicitly do not handle
Pre-1970 timezone accuracy for regions where the IANA database has incomplete historical data. The database is authoritative, but its coverage thins out before the Unix epoch. We document this limitation and return a flag in the meta block for conversions that fall before 1970 in affected regions.
We also don’t model the proposed changes — if a government announces a future DST change but it hasn’t been ratified into the IANA database yet, we use the current rules. The alternative is tracking unofficial announcements and applying them speculatively, which creates more problems than it solves.
Why this matters for your application
If your application schedules recurring events, calculates deadlines across timezones, or stores historical timestamps, these edge cases will eventually affect you. Not theoretically — they already affect you. The question is whether your code handles them correctly or silently gets them wrong.
The missing hour means a daily job scheduled at 2:30 AM might not run one day per year. The ambiguous hour means two events logged at the same timestamp might have been 30 minutes apart in real time, or simultaneous. The Samoa case means any system that validated event dates against “the current calendar” would have rejected legitimate Samoan dates in late 2011.
Timezone math is a solved problem in the sense that the IANA database contains the answers. It’s an unsolved problem in the sense that most applications don’t use it correctly. That gap is the deceptively hard part.