A Unix timestamp measures elapsed time from 1970-01-01 00:00:00 UTC. The number normally contains no timezone; its unit determines whether conversion produces the intended date.
The classic bug is a factor of 1,000: one system sends seconds while another expects milliseconds, producing 1970 or a far-future date. Digit count helps diagnosis, but explicit units are safer.
Epoch and timezone
Timestamp 0 identifies the UTC epoch. Positive values follow it and supported negative values precede it.
Timezone enters during human display. Shanghai and New York show different clocks for the same instant. Recurring local schedules need a timezone database, not only a timestamp.
Seconds, milliseconds, microseconds
Traditional Unix time uses seconds; JavaScript Date uses milliseconds; logs and traces may use microseconds or nanoseconds. A bare number cannot identify its unit.
Current dates are commonly 10 digits in seconds, 13 in milliseconds, and 16 in microseconds. Far dates break that heuristic.
| Unit | Current digits | To milliseconds |
|---|---|---|
| Seconds | 10 | × 1,000 |
| Milliseconds | 13 | unchanged |
| Microseconds | 16 | ÷ 1,000 |
| Nanoseconds | 19 | ÷ 1,000,000 |
JavaScript conversion
new Date(number) treats the number as milliseconds. Multiply seconds by 1,000. Date.getTime returns milliseconds; floor(Date.now()/1000) returns integer seconds.
Machine APIs should exchange ISO strings with Z or offsets, or numeric fields with named units. Date-time strings without offsets invite local-time ambiguity.
const ms = Date.now();
const sec = Math.floor(ms / 1000);
new Date(sec * 1000);
new Date(ms);Auto-detection limits
Magnitude is useful for pasted contemporary values. ToolGarden interprets below roughly 1e11 as seconds, below 1e14 as milliseconds, and larger values as microseconds, while allowing manual unit selection.
Do not rely only on string length: negatives, decimals, leading zeros, and distant dates complicate it. Show the interpreted unit before conversion.
Precision and leap seconds
JavaScript Number exactly represents integers only through 2^53−1. Practical millisecond epochs fit, but contemporary nanoseconds do not. Use BigInt or decimal strings when sub-millisecond digits matter.
Date stores milliseconds, so microsecond conversion loses detail. Unix time also does not normally represent leap seconds as distinct ordinary values.
Debugging checklist
Confirm unit first, then timezone, then parser assumptions. Compare raw number, ISO output, UTC, and local display. Name fields createdAtSeconds or createdAtMs rather than ambiguous createdAt.
- 1970: seconds likely treated as milliseconds.
- Far future: milliseconds likely multiplied again.
- Hour shift: inspect timezone.
- Lost ordering: sub-millisecond precision was discarded.
- Day shift: inspect date-only parsing.
Key takeaways
Unix timestamps are simple only when units are explicit. Normalize at boundaries, use milliseconds with JavaScript Date, preserve higher precision separately, and apply timezone rules during presentation or scheduling.