Time and data guide

Unix timestamp troubleshooting

How to diagnose wrong dates caused by units, timezone display, precision, and boundary assumptions.

First determine the unit

A Unix timestamp represents elapsed time from 1970-01-01 00:00:00 UTC, but software does not agree on the unit. Unix tools and many token formats use seconds. JavaScript's Date APIs commonly use milliseconds. Databases and telemetry systems may preserve microseconds or nanoseconds.

As a quick diagnostic, contemporary second values are about ten digits and millisecond values about thirteen digits. This is a clue, not a contract. Use the source documentation, then select the matching unit in the Unix Timestamp Converter. Multiplying a seconds value by 1,000 is appropriate only after the source unit is confirmed.

The timestamp is UTC; the display may not be

The numeric instant does not contain a timezone. A browser, log viewer, or database client may render the same instant in local time, UTC, or a configured region. Two different clock readings can therefore represent the same moment. Include an explicit offset or the letter Z when exchanging ISO 8601 values, and label screenshots or support notes with the display timezone.

Watch for rounding and boundaries

Converting milliseconds to integer seconds discards sub-second precision. Around midnight, month-end, daylight-saving transitions, or token expiry, that loss can change a comparison. Decide whether the application should floor, round, or preserve the fraction. For expiry checks, also document whether the system permits clock skew between machines.

Negative values represent instants before the epoch, but not every library or database column supports them. Very large values can overflow 32-bit signed storage. If a date wraps to 1901, 1970, or another implausible year, inspect the numeric type as well as the conversion formula.

Debugging checklist

1. Record the original numeric value without formatting it.
2. Confirm seconds, milliseconds, or another documented unit.
3. Compare the UTC rendering before applying local time.
4. Check precision and rounding at the boundary.
5. Verify the value in the source and destination runtimes.

Reference

The underlying Unix time behavior is documented by The Open Group time() specification. Calendar and timezone display rules remain properties of the consuming platform.