Unix Timestamps, Time Zones, and the Off-by-One-Hour Bug

Time bugs are sneaky because the code looks right and the numbers look plausible — they are just off by an hour, or a factor of a thousand, or a whole day at the month boundary. Most of these trace back to a single misunderstanding about what a Unix timestamp actually is.

What a Unix timestamp is (and isn't)

A Unix timestamp is the number of seconds elapsed since 1970-01-01 00:00:00 UTC. That is the entire definition. Crucially, it carries no time zone — it is an absolute instant. 1700000000 refers to the same moment everywhere on Earth; only its human rendering changes by zone.

This is the source of most confusion: the timestamp is unambiguous, but the string you print from it depends on which zone you format it in. Paste a value into the Unix Timestamp Converter and you can see both the UTC instant and your local rendering side by side, which immediately explains an "off by one hour" discrepancy.

The off-by-one-hour bug

Someone reports an event happened at "2:00 PM" but the logs say "1:00 PM." Nine times out of ten, one system formatted the same timestamp in UTC and the other in local time (or the difference is a daylight-saving offset). The timestamp is identical; the two renderings just used different zones. The fix is almost never "add an hour" — it is "decide which zone you display in, and be consistent." Storing and comparing in UTC, then formatting to the viewer's zone only at the edge, avoids the entire category.

Seconds vs milliseconds

The other classic trap: some systems count seconds (10 digits for current dates, like 1700000000) and others count milliseconds (13 digits, like 1700000000000). Feed a milliseconds value into something expecting seconds and your date lands roughly 50,000 years in the future; do the reverse and it snaps back to 1970. A quick length check catches it — 10 digits is seconds, 13 is milliseconds — and the Unix Timestamp Converter detects and handles both so you are not guessing.

A fast sanity check

When a timestamp looks wrong, run three checks before touching code:

1. Digit count — 10 (seconds) or 13 (milliseconds)? A wrong magnitude is the most common bug.
2. Zone — is the "wrong" time exactly your UTC offset away from the expected one? Then it is a formatting-zone issue, not a data issue.
3. Reasonableness — convert it. A value that renders as 1970 or the year 55000 is a units mismatch, not a real date.

If you are comparing two event times to find drift, convert both and diff them; the Diff Checker is handy when you are eyeballing two log lines that should line up but do not.

The habit that prevents it

Store instants as UTC timestamps, compare them as numbers, and format to a human zone only when you display. Keep seconds and milliseconds straight by checking digit count. Do that and the off-by-one-hour ghost — along with its 50,000-year cousin — stops haunting your logs. When one does slip through, the Unix Timestamp Converter turns "why is this date wrong?" into a five-second answer.