"An API returned 14:30 and another user sees 06:30" and "every due date the week we crossed DST came an hour early" are the same bug wearing two costumes: an absolute instant and a wall-clock value were treated as one thing. What follows walks storage, transport, arithmetic and display in order.
Everything starts from UTC
Every moment is physically unique. A Unix timestamp gives it a location-independent number; an ISO8601 string with an offset gives it a self-describing text form.
timestamp 1785891600000 (ms)
ISO8601 2026-09-04T09:00:00Z (UTC)
with offset 2026-09-04T17:00:00+08:00 (17:00 in Beijing)
Z means UTC, +08:00 means eight hours ahead, and all three point at the same instant — only the clock reading differs. An ISO8601 string without an offset is not an instant, it is a wall-clock reading, and every parser resolves it against the ambient zone; that is the door every incident below comes through.
DST makes a day stop being 24 hours
In North America spring-forward jumps 02:00 to 03:00, deleting that hour; fall-back drops 02:00 to 01:00, so 01:00-02:00 happens twice. One day therefore runs 23 hours and another 25. A literal "local 02:30" on the spring date either shifts to 03:30 or fails outright, and the same "01:30" in autumn maps to two distinct instants. Any date arithmetic that can cross a transition must happen on absolute instants.
The classic mistake: subtracting local calendars
// ❌ subtracting local times directly — off by an hour across DST
const hours = (new Date(b).getTime() - new Date(a).getTime()) / 3600e3
getTime() itself returns absolute milliseconds and is correct; the error is that both endpoints were built from local time, so the machine's zone has already absorbed the DST difference.
The fix: pin the instants first
// durations always come from absolute instants
const start = Date.parse('2026-03-07T00:00:00Z')
const end = Date.parse('2026-03-08T00:00:00Z')
const realHours = (end - start) / 3600e3
The IANA database keeps changing
Zones are political decisions, not physical constants: countries adopt or permanently drop DST, shift offsets and move switch dates, which is why IANA tzdata ships updates often. Never hardcode an offset or embed DST rules; use a maintained library and upgrade on its release cadence; and have APIs return the IANA zone name plus the current offset.
The three incidents share one skeleton
| Trigger | Symptom | Correct handling |
|---|---|---|
| Local time stored without its offset | The same row means different instants in different zones | Store UTC or offset-carrying ISO8601 |
| "30 local calendar days" used for renewal | An hour short or long across DST | 30 absolute days (24h×30) |
| Frontend rendered in the server's zone | Overseas users see every time shifted | Backend sends instants; frontend uses the browser zone |
All three are the same failure: an implicit assumption made where information was missing.
A one-glance checklist
storage → UTC / epoch / offset-carrying ISO8601 ✔
transport → ISO8601 with offset or Z ✔
display → browser local zone ✔
duration → always from absolute instants ✔
zone name → IANA name + current offset ✔
Reproducible Results
A fixed offset cannot express a zone, because New York's offset changes within a year:
from datetime import datetime
from zoneinfo import ZoneInfo
ny_jul = datetime(2025, 7, 1, 12, 0, tzinfo=ZoneInfo('America/New_York'))
ny_jan = datetime(2025, 1, 1, 12, 0, tzinfo=ZoneInfo('America/New_York'))
print(ny_jul.utcoffset()) # → -1 day, 20:00:00 (UTC-4, DST)
print(ny_jan.utcoffset()) # → -1 day, 19:00:00 (UTC-5, standard)
July and January differ by an hour under the same zone name — that is the entire reason "the same timestamp converts differently in winter and summer". Store UTC, convert at display time, name zones by IANA, and verify interactively with the timezone converter.