Date and Time Handling: The Bugs That Bite
Timezones, DST, leap seconds and floating clocks. Learn the rules, the storage format, and the bugs that appear twice a year.
By Velloreth
The two kinds of time
An instant is a point on the timeline. A log entry, a payment, a message.
A wall-clock time is a calendar time in a place. A meeting at 9am, a store that opens at 8am.
The rule:
| Kind | Store as |
|---|---|
| An instant | a timestamp in UTC |
| A wall-clock time | a local time plus a timezone |
| A calendar date | a date, with no time |
Confusing the two is the source of most date bugs.
A timezone is a rule set
An offset is a fixed number of hours.
+05:45
A timezone is a rule set that includes the offset and the daylight saving transitions.
Asia/Kathmandu
Why the distinction matters: the same place has two offsets across the year, and the rules change when a government changes them.
Store the timezone name, not the offset. An offset cannot be converted back.
DST
On the spring-forward day, a local time does not exist.
02:30 on the spring-forward day -> does not exist
On the fall-back day, a local time happens twice.
01:30 on the fall-back day -> happens twice
A naive local time is therefore ambiguous or invalid once a year.
The fix: store the instant in UTC, and convert for display.
A scheduled job at 2:30am on the spring-forward day does not run, or runs at a different time. A scheduler must define the behaviour.
The storage format
A timestamp in UTC.
created_at TIMESTAMPTZ -- Postgres: stores an instant
An ISO 8601 string with an offset.
2026-10-26T15:43:09+05:45
A date with no time.
birthday DATE
A duration as a number of seconds or milliseconds, not as a date.
The rule: the format carries the meaning. A string with no offset is ambiguous.
The bugs
Off by one day. A date parsed as midnight UTC and displayed in a negative offset becomes the previous day.
A birthday stored as a timestamp. The timezone of the server decides the day.
A duration added to a local time. The DST transition makes the result wrong by an hour.
A comparison across timezones. Two timestamps compared as strings, with different offsets.
A naive parse. new Date('2026-10-26') is parsed as UTC midnight in JavaScript, and new Date('2026-10-26T00:00:00') is parsed as local midnight. The two differ.
A leap second. A minute with 61 seconds, which a naive parser mishandles.
A clock that jumps. The system time is corrected and a duration measured with the wall clock is wrong.
The libraries
JavaScript: Temporal is the modern API, and date-fns or Luxon are the common libraries. The built-in Date is a timestamp with a local-time API, which is the source of the confusion.
Python: datetime with zoneinfo, and dateutil for parsing.
Java: java.time, with Instant, ZonedDateTime and LocalDate.
Go: time.Time with a location, and time.Duration for a duration.
The rule: use a library that knows the timezone database, and never do the arithmetic by hand.
The rules
Store an instant in UTC.
Store a wall-clock time with its timezone.
Store a date as a date.
Convert at the boundary, which is the display and the input.
Use a monotonic clock for a duration.
Test the DST transitions. A test that runs on the transition day is the one that catches the bug.
Send an ISO 8601 string with an offset across an API.
Never compare a local time to a UTC time.
Common mistakes
A naive local time in the database. Ambiguous once a year.
An offset instead of a timezone. Cannot be converted back.
A date stored as a timestamp. An off-by-one-day bug.
A duration added to a local time. Wrong across a DST transition.
A string comparison of timestamps. Wrong across offsets.
A wall clock for a duration. Wrong when the clock is corrected.
No DST test. The bug appears twice a year.
A hardcoded offset. Breaks when the rules change.
A date format that is ambiguous. 03/04/2026 is two different days.
A quotable summary
Store an instant in UTC and a wall-clock time with its timezone, because a timezone is a rule set and not a fixed offset. DST makes a local time ambiguous or nonexistent once a year, so a naive local time is a bug waiting to happen. Keep a date as a date, a duration as a number, use a monotonic clock for a duration, and convert only at the display boundary.
Related reading
For the related topics, see timezones-in-software and json-vs-yaml-vs-toml. For the broader context, unicode-and-encoding and floating-point-precision.