Debugging Epoch Timestamp Issues — Common Pitfalls

Debugging Epoch Timestamp Issues

Timestamp bugs are among the most frustrating to debug because they often produce results that look almost correct. Here are the most common pitfalls and how to fix them.

Pitfall 1: Seconds vs Milliseconds

Symptom: Dates appear as January 1970 or year 55,000+

// Bug: passing seconds to a function expecting milliseconds
new Date(1705312200)      // 1970-01-20T17:21:52.200Z (wrong!)
new Date(1705312200000)   // 2024-01-15T09:30:00.000Z (correct)

Fix: Always check the digit count. 10 digits = seconds, 13 = milliseconds.

Pitfall 2: Timezone Mismatch

Symptom: Timestamps are off by exactly N hours

# Bug: creating datetime without timezone info
from datetime import datetime
dt = datetime(2024, 1, 15, 9, 30, 0)
epoch = dt.timestamp()  # Uses local timezone! Wrong if server is not UTC

# Fix: always specify UTC
from datetime import timezone
dt = datetime(2024, 1, 15, 9, 30, 0, tzinfo=timezone.utc)
epoch = dt.timestamp()  # Correct

Pitfall 3: Daylight Saving Time

Symptom: Countdown jumps by exactly 1 hour at DST transition

DST transitions cause one hour to either repeat or be skipped. If your countdown uses local time arithmetic, it will be wrong for one hour twice a year. Always use UTC epoch timestamps for interval calculations.

Pitfall 4: 32-bit Overflow

Symptom: Dates after 2038-01-19 appear as dates in 1901

This is the Y2K38 problem. If your system uses a 32-bit integer for timestamps, values above 2,147,483,647 overflow to negative.

Fix: Use 64-bit integers (BIGINT in SQL, long in Java, int64 in Go).

Pitfall 5: Floating-Point Precision

Symptom: Timestamps lose precision in fractional seconds

// JavaScript number precision issue
const epoch = 1705312200.123456789;
console.log(epoch);  // 1705312200.1234567 (last digits lost)

IEEE 754 double-precision floats have about 15-16 significant digits. For nanosecond-precision timestamps (19 digits), use strings or BigInt.

Debugging Checklist

1. Check the unit (seconds, milliseconds, microseconds)
2. Check the timezone (UTC vs local)
3. Check the integer size (32-bit vs 64-bit)
4. Check the parsing format (epoch vs ISO 8601 mismatch)
5. Check DST transitions around the problematic time
6. Check for off-by-one errors in month indexing (JavaScript months are 0-based)