Skip to content
Velloreth
Programming 4 min read

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

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:

KindStore as
An instanta timestamp in UTC
A wall-clock timea local time plus a timezone
A calendar datea 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.

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.

Frequently asked questions

Should I store dates in UTC?
Store an instant, such as a timestamp, in UTC. Store a wall-clock time, such as a meeting at 9am, with its timezone, because 9am in Kathmandu and 9am in London are different instants. The distinction is between a moment and a calendar time, and confusing them is the source of most date bugs.
What is a timezone offset versus a timezone?
An offset is a fixed number of hours from UTC, such as +05:45. A timezone is a rule set that includes the offset and the daylight saving transitions, such as Asia/Kathmandu. An offset is not enough, because the same place has two offsets across the year.
What is the DST bug?
On the spring-forward day, a local time such as 2:30am does not exist, and on the fall-back day it happens twice. A naive local time is therefore ambiguous or invalid once a year. The fix is to store the instant in UTC and to convert for display, and to use a timezone-aware library.
What is the difference between a timestamp and a date?
A timestamp is an instant, a point on the timeline, and it is unambiguous. A date is a calendar day, which is a range of instants that depends on the timezone. A birthday is a date, and a log entry is a timestamp. Storing a birthday as a timestamp introduces a timezone bug.
Why is my date off by one day?
The common causes are a naive local time converted to UTC, a date parsed as midnight UTC and displayed in a negative offset, and a date stored as a string with a different format. The fix is to keep a date as a date, to store an instant in UTC, and to convert only at the display boundary.
What is a monotonic clock?
A clock that only moves forward and is not affected by a time adjustment. It is used to measure a duration, because the wall clock can jump backward when the system time is corrected. Use a monotonic clock for a timeout and a wall clock for a timestamp.