Timezone & DST Pitfalls: Why Your Timestamps Are Always an Hour Off

"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.

Frequently Asked Questions

Should I store UTC or local time?

Store and transmit in UTC (or ISO8601 with its explicit offset); convert to local only for display. Absolute moments are physical and objective, but 'what time is it' depends on the observer's zone and changes with travel and DST. Storing local time without the offset makes one row read as different moments in different zones; storing UTC converts correctly everywhere regardless of DST. Practice: use TIMESTAMP WITH TIME ZONE / epoch in databases and return ISO8601 with +08:00 or Z from APIs.

Why do some duration calculations gain or lose an hour around DST?

DST makes a day 23 or 25 hours long. In the spring-forward transition the local hour 02:00-03:00 doesn't exist; in fall-back the hour 01:00-02:00 occurs twice. If you compute elapsed time by subtracting two local calendar times, that day ends up an hour off. Correct: convert both endpoints to absolute moments (instant/UTC) and subtract, or be explicit about physical duration—a day is 24h, a week 168h, and only a 'day' spanning DST is not 24h.

Why must display include a timezone rather than just numbers?

Because the same 14:30 points to different absolute instants in different zones; bare numbers lose the meaning. ISO8601 standard is to suffix the offset: 2026-09-04T14:30:00+08:00 (or Z for UTC). Any parser can then recover the instant and render it in the audience's local zone. Best practice: the backend hands out absolute instants (with offset) and the frontend renders using the browser's local zone—servers never know where the user is and shouldn't decide what clock to show.

Why do some countries'/regions' time zones change?

Time zones aren't physics; they're politics and legislation. Countries shift offsets, adopt/permanently-abandon DST, or change switch dates (Turkey, Egypt, Mexico and others did recently)—which is why the IANA tzdata database ships updates frequently. Consequence: hardcoded offsets (e.g. +08:00) or embedded DST rules rot over time; always use a maintained timezone library with updates, and have APIs return the up-to-date IANA zone name (e.g. Asia/Shanghai, America/New_York) along with the current offset for display.

← Back to Blog