Unix Timestamp Debugging: Seconds, Milliseconds, UTC, and Time Zones

Timestamp bugs are common because a Unix timestamp is simple but the systems around it are not. A number may represent seconds or milliseconds. A database may store UTC while the UI displays local time. A log line may use ISO 8601 while an API sends epoch time. Around daylight saving time, even "midnight" can become surprisingly fragile.

This guide gives you a reliable way to debug timestamp problems.

Start with the unit

The first question is always: seconds or milliseconds?

Traditional Unix time is seconds since 1970-01-01 00:00:00 UTC. JavaScript Date, Java System.currentTimeMillis(), and many frontend APIs use milliseconds.

Typical lengths:

  • 10 digits: seconds, for example 1721347200
  • 13 digits: milliseconds, for example 1721347200000

If a date appears around 1970, you probably passed seconds into a function that expected milliseconds. If a date appears thousands of years in the future, you probably multiplied milliseconds by 1000 again.

// seconds to JavaScript Date
new Date(1721347200 * 1000)

// milliseconds to JavaScript Date
new Date(1721347200000)

UTC storage, local display

A Unix timestamp represents one absolute moment. It does not contain a time zone. Time zones only appear when you display that moment as a calendar date.

For example, the same timestamp can display as different local times in New York, London, Shanghai, and Tokyo. This is expected. The timestamp did not change; the display rules changed.

When debugging, compare both values:

const d = new Date(1721347200 * 1000)
console.log(d.toISOString()) // UTC
console.log(d.toString())    // local time

If the UTC value is correct but the UI looks one day off, the issue is probably local time-zone rendering, not the timestamp itself.

Date-only values are risky

Date-only strings such as 2026-07-19 are easy to misuse. Some systems interpret them as UTC midnight. Others interpret them as local midnight. When converted to a timestamp, users in different time zones may see the previous or next date.

For user-facing dates, store the original date if it is a calendar concept such as birthday, invoice date, or event day. Do not force every date-only value into a timestamp unless you truly need an exact moment.

Daylight saving time

Daylight saving time makes local time discontinuous. A local hour may be skipped or repeated. If you schedule jobs at local 02:30, there may be days when that time does not exist or occurs twice.

For systems that must be reliable:

  • store timestamps in UTC
  • store the user's time zone separately when needed
  • convert to local time only at the display boundary
  • avoid calculating "one day later" by adding exactly 86400 seconds when the user expects local calendar days

Database and API checklist

When debugging a timestamp crossing a database/API boundary, write down:

  1. raw value
  2. unit: seconds or milliseconds
  3. UTC ISO string
  4. local display string
  5. database column type
  6. API contract

This catches most mistakes quickly. A BIGINT column may hold epoch milliseconds, while a timestamp with time zone column may already store a normalized instant. A JSON API may document seconds but frontend code may send milliseconds.

Logs and monitoring

Logs often mix formats:

2026-07-19T10:30:00Z
1721385000
1721385000000
Jul 19 18:30:00

Normalize everything before comparing events. Use UTC ISO strings as the debugging baseline because they are readable and unambiguous.

When two systems seem out of order, verify:

  • are both clocks synchronized?
  • are both timestamps in the same unit?
  • does one value represent receive time while another represents event time?
  • does one log viewer display local time while another displays UTC?

JavaScript parsing warning

JavaScript date parsing is permissive but not always portable. Prefer explicit timestamps, ISO strings with time zone, or form fields that you convert intentionally.

Good:

new Date('2026-07-19T10:30:00Z')
new Date(1721385000000)

Risky:

new Date('2026/07/19 10:30:00')
new Date('07/19/2026')

Ambiguous strings may parse differently across browsers or environments.

A practical debugging flow

Use the Unix Timestamp Converter to convert the raw value both ways. If the tool shows the correct UTC moment, inspect your UI display logic. If the tool shows the wrong moment, inspect the unit and the source system.

For payloads that include timestamps inside JSON, validate the structure with the JSON Formatter. For URL parameters such as ?expires=1721385000, use the URL parameter parser to isolate the value before converting it.