📚 Part of the What is a Unix Timestamp? Understanding Epoch Time in Modern Programming series.
Unix Epoch Time Converter
Convert Unix timestamps to dates and dates to epoch time instantly. Supports milliseconds, timezones, and multiple formats.
Open the full Unix Epoch Time Converter tool →The Most Common Unix Timestamp Mistakes
Working with Unix timestamps seems simple but harbors subtle traps that catch even experienced developers. Understanding common pitfalls helps you avoid them.
Mistake #1: JavaScript's Millisecond Confusion
The Problem:
JavaScript's Date object and Date.now() use milliseconds since epoch, not seconds. Most other systems use seconds.
The Error:
// Wrong: Treats timestamp as milliseconds
const timestamp = 1704067200; // Actually Jan 1, 2024
const date = new Date(timestamp);
console.log(date); // Shows 1970-01-20 (completely wrong!)
// Correct: Multiply by 1000 to convert seconds to milliseconds
const date = new Date(timestamp * 1000);
console.log(date); // 2024-01-01T00:00:00.000Z
Why It Happens:
JavaScript's Date uses milliseconds for historical reasons. Developers coming from Unix systems (which use seconds) frequently make this mistake.
Prevention:
- Always multiply by 1000 when converting Unix seconds to JavaScript milliseconds
- Use
Math.floor(Date.now() / 1000)to get Unix seconds - Add a comment:
// Milliseconds in JavaScript
Mistake #2: Timezone Confusion
The Problem: Unix timestamps are always UTC. Converting to/from local time is a common source of errors.
The Error:
// Wrong assumption: Date string without timezone is UTC
const dateString = "2024-01-01 12:00:00";
const timestamp = new Date(dateString).getTime() / 1000;
// Actually uses local time, not UTC!
// Correct: Explicitly specify UTC
const timestamp = new Date("2024-01-01T12:00:00Z").getTime() / 1000;
// or
const timestamp = Date.UTC(2024, 0, 1, 12, 0, 0) / 1000;
Real-World Impact:
// In New York (UTC-5)
const timestampWrong = new Date("2024-01-01 12:00:00").getTime() / 1000;
// Interprets as EST: 12:00 EST = 17:00 UTC (wrong!)
// In Tokyo (UTC+9)
// Same code: 12:00 JST = 03:00 UTC (different wrong answer!)
// Correct approach
const timestampCorrect = new Date("2024-01-01T12:00:00Z").getTime() / 1000;
// Always 12:00 UTC regardless of system timezone
Prevention:
- Always use ISO format with 'Z' for UTC:
2024-01-01T12:00:00Z - Be explicit about timezone conversions
- Test in different timezones if working with time-sensitive code
Mistake #3: Month Off-by-One Error
The Problem: Many programming languages (JavaScript, Python, some others) use zero-indexed months.
The Error:
// JavaScript: Months are 0-indexed!
const date = new Date(2024, 0, 1); // Month 0 = January (correct by accident)
const date2 = new Date(2024, 1, 1); // Month 1 = February (not March!)
// Wrong
const date3 = new Date(2024, 3, 1); // Expected April? Actually April (0-indexed!)
// Correct way
const date = new Date(2024, 0, 1); // January (month 0)
const date2 = new Date(2024, 11, 1); // December (month 11)
// Or use ISO format to avoid confusion
const timestamp = new Date("2024-04-01T00:00:00Z").getTime() / 1000;
Python (Different Problem):
from datetime import datetime
# Python uses 1-indexed months (more intuitive)
date = datetime(2024, 1, 1) # January 1st
date = datetime(2024, 4, 1) # April 1st
# But when formatting, easy to make mistakes
timestamp = int(date.timestamp())
# This gives local time, not UTC!
# Correct
timestamp = int(date.replace(tzinfo=timezone.utc).timestamp())
Prevention:
- Use ISO date strings (
YYYY-MM-DD) to avoid month confusion - Check documentation for your language's month indexing
- Use date libraries that handle this automatically
Mistake #4: Assuming Consistent Seconds Per Time Unit
The Problem: Not all minutes have 60 seconds, not all days have 24 hours (leap seconds exist), not all years have the same length.
The Error:
// Wrong: Assumes every year is exactly 365 days
const secondsPerYear = 365 * 24 * 60 * 60; // 31,536,000
const ageInYears = totalSeconds / secondsPerYear;
// Off by ~1 day per 4 years!
// Better: Use date math
function getAgeInYears(birthTimestamp) {
const now = new Date();
const birth = new Date(birthTimestamp * 1000);
let age = now.getFullYear() - birth.getFullYear();
const monthDiff = now.getMonth() - birth.getMonth();
if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < birth.getDate())) {
age--;
}
return age;
}
Real-World Impact:
// Leap year effects
2024 is a leap year: 366 days = 31,622,400 seconds
2025 is not: 365 days = 31,536,000 seconds
Difference: 86,400 seconds (1 full day)
// Using average seconds causes 1-day errors every 4 years
Prevention:
- Use date libraries for human-time calculations
- Use simple Unix arithmetic only for short periods (hours, minutes)
- For years/months, use proper date math
Mistake #5: Epoch Time Misunderstanding
The Problem: Confusion about what "Unix epoch" is or assuming it applies universally.
The Error:
// Wrong: Assuming negative timestamps don't exist
const timestamp = -86400; // Valid! Represents Jan 1, 1970 minus 1 day
console.log(new Date(timestamp * 1000)); // 1969-12-31
// Wrong: Assuming Unix epoch is midnight local time
// Unix epoch is Jan 1, 1970 00:00:00 UTC, not your local midnight
// Wrong: Assuming timestamp 0 is the beginning of "today"
const today = 0; // Nope, this is Jan 1, 1970 in UTC
Prevention:
- Remember: Unix epoch is specifically January 1, 1970, 00:00:00 UTC
- Negative timestamps are valid (pre-1970 dates)
- Timestamp 0 is always the same moment worldwide
Mistake #6: Leap Second Ignoring
The Problem: Unix timestamps don't account for leap seconds. When a leap second occurs, the timestamp "jumps over" that second.
The Error:
// On June 30, 2015, a leap second was added
// The second at 23:59:60 UTC was inserted
// Unix timestamps skip this: ...1435708799, 1435708800, 1435708801...
// (There is no timestamp for the leap second)
// Wrong: Assuming every second has exactly one timestamp
const timestamp1 = 1435708799;
const timestamp2 = 1435708800;
const diff = timestamp2 - timestamp1; // 1 second (correct, but skipped leap second)
Real-World Impact: This affects systems that need nanosecond precision or atomic time. Most applications can ignore it.
Prevention:
- Awareness that leap seconds exist
- Use UTC timestamps (not TAI) if leap seconds matter
- Most applications don't need to worry about this
Mistake #7: String Concatenation Instead of Conversion
The Problem: Treating timestamps as strings instead of numbers.
The Error:
// Wrong
const timestamp = "1704067200";
const futureTime = timestamp + 86400; // "1704067200" + 86400 = "170406720086400"
console.log(futureTime); // String concatenation, not addition!
// Correct
const timestamp = parseInt("1704067200");
const futureTime = timestamp + 86400; // 1704153600
In SQL:
-- Wrong
SELECT timestamp + interval '1 day'
FROM events
WHERE timestamp = "1704067200"; -- String comparison!
-- Correct
SELECT timestamp + INTERVAL '1 day'
FROM events
WHERE timestamp = 1704067200; -- Numeric comparison
Prevention:
- Always parse timestamps as numbers
- Use strict typing in languages that support it
- Be explicit:
parseInt(),float(), etc.
Mistake #8: Sign Confusion
The Problem: Working with timestamps, you might accidentally flip the subtraction order.
The Error:
// Want time until expiration
const expirationTime = 1706745600;
const now = 1704067200;
// Wrong: Negative result (past time)
const timeUntilExpiry = now - expirationTime; // Negative!
// Correct
const timeUntilExpiry = expirationTime - now; // Positive
Prevention:
- Add comments indicating direction: "end - start" not "start - end"
- Check for negative values and handle appropriately
- Use absolute value if direction doesn't matter
Mistake #9: Daylight Saving Time Issues
The Problem: When handling local times, DST transitions cause issues.
The Error:
// During DST transition (2:00 AM becomes 3:00 AM)
// Times become ambiguous
// Don't try to construct times manually during DST transition
// Instead, use strings and let the parser handle it
const date = new Date("2024-03-10T02:30:00-05:00"); // EDT vs EST ambiguous
// Correct: Use library that handles DST
import { DateTime } from "luxon";
const dt = DateTime.fromISO("2024-03-10T02:30:00", { zone: "America/New_York" });
Prevention:
- Always use proper date/time libraries (not manual calculation)
- When possible, work entirely in UTC
- Test code during DST transitions
Mistake #10: Assuming Monotonic Timestamps
The Problem: Assuming that time always moves forward (it doesn't when clocks are adjusted).
The Error:
// Wrong: Assuming this always increases
let lastTimestamp = Date.now() / 1000;
// ... later ...
let currentTimestamp = Date.now() / 1000;
// If system clock is adjusted backward, currentTimestamp < lastTimestamp!
// Better: Check for backward time
if (currentTimestamp < lastTimestamp) {
console.warn("System clock was adjusted backward!");
currentTimestamp = lastTimestamp; // Use last known time
}
Prevention:
- Check for negative time deltas
- Use monotonic clocks if available (
process.hrtime()in Node.js) - Handle time-adjustment scenarios gracefully
Testing Timestamp Code
Create Test Cases:
// Test basic conversion
assert(convertToTimestamp("2024-01-01T00:00:00Z") === 1704067200);
// Test timezone handling
assert(convertToTimestamp("2024-01-01T00:00:00Z") ===
convertToTimestamp("2024-01-01T05:00:00+05:00"));
// Test edge cases
assert(isValidTimestamp(-86400)); // Pre-1970 should be valid
assert(isValidTimestamp(0)); // Epoch is valid
assert(isValidTimestamp(253402300799)); // Year 9999
// Test rounding
assert(calculateAge(birthTimestamp) < 150); // Sanity check
Using the Unix Timestamp Converter for Verification
The Unix Timestamp Converter helps verify your work:
- Convert your calculated timestamp back to a readable date
- Verify the date matches expectations
- Check timezone handling
Example workflow:
Calculate: 1704067200 + 86400
Verify: Convert result to readable format
Expected: Jan 2, 2024
Conclusion: Vigilance Prevents Timestamp Bugs
Timestamp errors are among the most frustrating bugs because they often work 99% of the time, failing only on edge cases (leap years, DST transitions, timezone changes). Understanding these common mistakes—JavaScript milliseconds, timezone confusion, off-by-one errors, and DST effects—helps you write robust time-handling code. Use the Unix Timestamp Converter to verify your calculations, test edge cases thoroughly, and prefer date libraries over manual calculation whenever possible.