Unix time and time zones: a practical guide for developers

Updated 2026-10-21. Unix timestamps are useful because they reduce a moment to a number. They are also a common source of bugs: a value may be in seconds or milliseconds, a display may be local rather than UTC, and daylight saving time can make a clock label look ambiguous. This guide separates the instant from its presentation and gives examples you can reproduce with our Unix timestamp converter.

Unix time in one sentence

Unix time counts seconds from 1970-01-01T00:00:00Z, the Unix epoch. The trailing Z means UTC. A timestamp identifies an instant; it does not contain a time-zone name. The value 0 is the epoch, and 1 means one second later. Negative values represent instants before 1970. Unix time is normally discussed in whole seconds, although applications often store fractions or use milliseconds.

That distinction matters in logs and APIs. A database column called created_at may contain an ISO string, an integer in seconds, or an integer in milliseconds. The label alone is not enough. Check the API contract, the magnitude, and a known event before converting a value.

Seconds, milliseconds, and the unit trap

JavaScript's Date constructor expects milliseconds since the epoch. If your source is Unix seconds, multiply by 1,000 before constructing the date. For example, 1717286400 seconds becomes 1717286400000 milliseconds. Both values identify 2024-06-02T00:00:00.000Z. Passing seconds directly to JavaScript produces a date only about 20 days after 1970, which can look valid enough to escape a quick review.

A magnitude check is a useful hint, not proof. Current ten-digit values are usually seconds and thirteen-digit values are usually milliseconds, but old records, future dates, fractional values, and microseconds break that shortcut. When investigating a production timestamp, compare it with a log line whose wall-clock time is known. Convert it both ways and reject the interpretation that cannot match the event.

Three worked conversions

  1. Epoch zero. Input 0 as seconds. The UTC result is 1970-01-01T00:00:00.000Z. This is a good smoke test because it has no rounding or timezone ambiguity.
  2. A current-looking seconds value. Input 1717286400 seconds. Multiply by 1,000 for JavaScript and the result is 2024-06-02T00:00:00.000Z.
  3. The same instant in milliseconds. Input 1717286400000 milliseconds. It produces the identical UTC instant. The only difference is the unit and the number of zeroes.

The epoch converter accepts seconds and milliseconds and can annotate timestamp-like values in log text. For a line such as started_ms=1717286460000, the useful result is the original line plus the decoded instant; keep the raw value in the log so another system can audit the conversion.

UTC is the instant; local time is a view

When a browser shows a local date, it has not changed the timestamp. It has applied the viewer's time-zone rules to the same instant. A UTC time of 2024-06-02T00:00:00Z is one clock label in Dublin, another in New York, and another in Tokyo. Store instants in UTC or an unambiguous offset, then choose a display zone for the person reading the result.

Do not describe a Unix timestamp as “Dublin time” or “Irish time.” Store a zone separately when the user means a recurring local event, such as “09:00 Europe/Dublin.” For a meeting, the instant and the intended zone are both relevant. For an audit event, the instant is usually the primary fact.

Europe/Dublin and daylight saving time

Europe/Dublin does not have one fixed offset throughout the year. Its civil-time rules include seasonal changes, and the exact transition dates are maintained in the IANA time-zone database. A conversion made for an Irish user should therefore use the named zone, not a hard-coded “UTC+1” rule. The IANA time-zone database is the authoritative source for zone identifiers and historical rules; JavaScript's Date documentation explains how date values are represented.

On an autumn transition, a local clock label can occur twice. On a spring transition, some local labels do not occur at all. The timestamp remains unambiguous when represented in UTC, but a bare local string such as “01:30” is not enough to identify an event. Include an offset or the zone and a disambiguation policy.

Invalid, negative, fractional, and future values

Zero and negative values are valid timestamps; they describe the epoch and earlier instants. A fractional value may represent sub-second precision, but you must know whether the source uses decimal seconds or another unit. Reject non-numeric text, impossible dates, and values outside the range your runtime can represent. A very large integer might be microseconds or nanoseconds rather than a far-future millisecond date. Never silently “fix” an input by guessing its unit in a data migration.

Practical checklist

Designing timestamp fields in an application

Make the unit impossible to miss. Names such as created_at_unix_seconds or expires_at_ms are safer than a generic time. A JSON API can use an ISO 8601 string with a trailing Z, which is readable and carries the UTC convention. If an API must use an integer, document whether it is seconds, milliseconds, microseconds, or nanoseconds and whether fractional values are allowed.

When a service receives an event, preserve the original payload and record the parsed instant separately. This makes a parser bug recoverable. In tests, freeze the clock and assert both the numeric value and the formatted output. Test a leap-year date, a pre-epoch value, a fractional input, and a date around a Europe/Dublin transition. Do not use a server's local timezone as an implicit business rule.

Debugging an apparent one-hour error

First compare UTC labels, not local labels. Then check whether one side parsed an ISO string without an offset, whether the other side used a fixed offset instead of Europe/Dublin, and whether seconds were mistaken for milliseconds. A one-hour difference around a clock change is often a zone-rule problem, while a difference of roughly 1,000 times the expected interval is usually a unit problem. Record the exact input, parser, runtime and zone when reporting the defect.

A useful incident note says: “Raw value 1717286400, interpreted as seconds; UTC instant 2024-06-02T00:00:00Z; displayed in Europe/Dublin; source field contract X.” That is much more actionable than “the date is wrong.” It lets another engineer reproduce the calculation and distinguish data corruption from a display preference.

When a timestamp is not enough

Some requirements describe a calendar event rather than a past instant. “Run at 09:00 in Dublin every weekday” needs a recurrence rule and the Europe/Dublin zone. Converting the next occurrence to a Unix value is useful for execution, but storing only that next value loses the rule and will become wrong after a transition. Conversely, “the payment arrived at this instant” should be stored as an instant; it should not be reconstructed from a local calendar date later.

For distributed systems, use a consistent representation at service boundaries and include a correlation identifier with the event. Clock skew can make two machines disagree slightly, so ordering by timestamps alone may be unsafe for events that arrive close together. If exact ordering matters, use the system's sequence or transaction order as well as the timestamp. These are design choices, not problems that a converter can solve, but making them explicit prevents many date bugs.

Parsing and formatting safely

Parse a timestamp once at the boundary of your program and pass a typed instant through the rest of the code. Format only at the edge where a person or external system needs a label. This avoids repeated timezone conversions and makes tests clearer. If a user enters a local date and time, ask for the intended zone; without it, the input cannot be converted reliably around daylight-saving transitions.

Testing timestamp code

A small test matrix catches more defects than a single happy-path assertion. Include the epoch, a recent known instant, a pre-1970 value, a fractional value, and both seconds and milliseconds for the same moment. Add cases immediately before and after a Europe/Dublin offset transition, then test an ambiguous local label with the policy your application has chosen. Assert the parsed instant and the displayed text separately: a correct instant can still be formatted in the wrong zone.

Keep fixture values explicit and stable. Avoid tests that depend on the machine's current clock or local timezone, because they may pass on a laptop and fail in CI. Freeze time where the code creates a “now” value, set the formatter's zone deliberately, and include the input unit in the fixture name. If you accept external timestamps, test malformed text, missing offsets, oversized integers, and values outside the supported date range. Logging the rejected value and reason helps operators repair data without silently changing its meaning.

Sources and related tools

Primary references: IANA Time Zone Database and MDN Date. For schedules that repeat in local time, use the cron expression builder. For the hands-on conversion, use the epoch converter.