Unix Timestamp Converter: Fix Wrong Millisecond Dates

1697284005 vs 1697284005000: One Gives October 14, 2023, the Other Gives January 20, 1970

You paste a timestamp into your Unix timestamp converter. You expect October 14, 2023, at 3:46 PM UTC. Instead, you get a date in 1970, or 2023, or sometimes a year so far in the future it looks like a typo. The number is the same. The converter is the same. The result is wrong.

Here is the disconnect: 1697284005 is a Unix timestamp in seconds. 1697284005000 is the same moment in milliseconds. Most online converters assume seconds. Most modern programming languages — JavaScript, Python's datetime.fromtimestamp() with default arguments, Java's Instant.ofEpochSecond() — expect you to be explicit. When you feed a millisecond value into a converter that interprets it as seconds, the math explodes quietly, and the tool returns a date that looks plausible but is off by decades.

This article walks through a real debugging workflow I use when a timestamp converter returns the wrong date for millisecond-based epoch values. We will trace one value end-to-end, compare the correct path against the broken path at each stage, and build a conversion routine that defends against the ambiguity.

The Core Mismatch: Seconds-Based Epoch vs Millisecond-Based Epoch

What a Unix Timestamp Actually Represents

A Unix timestamp counts seconds elapsed since January 1, 1970, 00:00:00 UTC — the Unix epoch. That is the original specification. A 10-digit number like 1697284005 fits this definition cleanly.

Millisecond timestamps are a later convention. JavaScript's Date.now() returns milliseconds. Java's System.currentTimeMillis() returns milliseconds. Most browser APIs, most logging frameworks built on top of JS, and most NoSQL document stores that serialize dates as numbers use milliseconds. The number grows by three orders of magnitude: 1697284005000 instead of 1697284005.

Contrast: Correct Interpretation vs Broken Interpretation

Take the value 1697284005000.

Correct path — treat as milliseconds:

• 1697284005000 ÷ 1000 = 1697284005 seconds
• Convert seconds since epoch → October 14, 2023, 15:46:45 UTC

Broken path — treat as seconds:

• 1697284005000 seconds since epoch
• 1697284005000 ÷ 31,536,000 (seconds per year) ≈ 53,738 years after 1970
• Result: a date roughly in the year 55,708

Most converters do not show you the year 55,708. They overflow, wrap, or clamp. You see 1970, 2001, or an error. The tool is not broken — your input assumption is.

Detecting the Mismatch in Your Own Pipeline

Let us trace a real value through a typical ingestion workflow. Suppose your application receives a payload from a third-party API:

{"event_id": "evt_8821", "created_at": 1697284005000}

You run this through a Unix timestamp converter on your dashboard. The date renders as January 20, 1970. Here is how to diagnose it.

Step 1: Count the Digits

This is the fastest heuristic.

• 10 digits → almost certainly seconds. Current range: roughly 946,684,800 (year 2000) to 4,102,444,800 (year 2100).
• 13 digits → almost certainly milliseconds. Current range: 946,684,800,000 to 4,102,444,800,000.
• 16 digits → microseconds. Common in high-resolution logging.
• 19 digits → nanoseconds. Common in tracing systems like OpenTelemetry.

1697284005000 has 13 digits. It is milliseconds. If your converter is built for seconds, it will misinterpret this by a factor of 1,000.

Step 2: Sanity-Check Against "Now"

Compare the timestamp against the current epoch. As of late 2023, a seconds-based timestamp sits around 1.7 × 10⁹. A millisecond-based timestamp sits around 1.7 × 10¹².

If your value is 1.697 × 10¹² and your converter returns 1970, the converter divided by nothing. It treated the raw number as seconds. That is the bug.

Contrast: Two Converter Behaviors

Naive converter (seconds-only):

• Input: 1697284005000
• Internal: new Date(1697284005000) interpreted as seconds
• Output: 1970-01-20 (wrong)

Defensive converter (auto-detect):

• Input: 1697284005000
• Internal: digit count = 13 → divide by 1000
• Output: 2023-10-14 15:46:45 UTC (correct)

The difference is not the math. The difference is the assumption.

Fixing the Converter: A Step-by-Step Workflow

Let us build the fix. I will use the value 1697284005000 throughout so you can verify each step.

Step 1: Normalize the Input to Seconds

Before converting, reduce every timestamp to seconds. This is the canonical Unix format.

• If digits ≥ 16: divide by 1,000,000 (microseconds → seconds)
• If digits ≥ 13: divide by 1,000 (milliseconds → seconds)
• If digits ≥ 10: keep as-is (seconds)

For our value: 1697284005000 ÷ 1000 = 1697284005.

Step 2: Convert Using an Explicit UTC Baseline

Never rely on the local system timezone during conversion. Always anchor to UTC, then offset only for display.

In JavaScript, the correct call is:

new Date(1697284005000).toISOString()

Note: JavaScript's Date constructor expects milliseconds natively. This is why JS developers often get confused — they assume every converter works the same way. It does not.

In Python, the correct call is:

datetime.datetime.fromtimestamp(1697284005, tz=datetime.timezone.utc)

Python's fromtimestamp expects seconds by default. If you pass 1697284005000 without dividing, Python returns OverflowError or a date in the year 56,000+ depending on version.

Contrast: Same Value, Two Languages, Two Default Assumptions

Same number. Different default. This is why a converter that works in your browser breaks in your backend.

Validating Across Timezones and Display Formats

Once the seconds value is correct, the next failure point is timezone rendering. You converted 1697284005 correctly to October 14, 2023, 15:46:45 UTC. But your user is in Tokyo. They see October 15, 2023, 00:46:45 JST. They report it as "wrong."

It is not wrong. It is localized.

Correct Path: UTC-First, Local Second

1. Store and convert in UTC. Always.
2. Render in the user's local timezone only at the presentation layer.
3. Label the timezone explicitly in the output string.

Broken Path: Local-First Conversion

1. Convert using server local time.
2. Cache the rendered string.
3. Serve it to users in other timezones.
4. Result: every user east of your server sees a date that is "off by a day."

The timestamp 1697284005 is unambiguous. The display of it is where ambiguity creeps back in.

Building a Defensive Unix Timestamp Converter

If you are shipping a Unix timestamp converter as a tool — internal dashboard, public utility, or SDK helper — it must handle the seconds/milliseconds ambiguity automatically. Here is the contract I use:

1. Accept numeric input only. Reject strings that cannot be parsed to integers.
2. Count digits. Use the heuristic above to infer the unit.
3. Normalize to seconds internally. One code path, one unit, one source of truth.
4. Convert in UTC. Attach tz=UTC explicitly.
5. Return both ISO 8601 and human-readable formats. Include the timezone offset in the output so the user can verify.
6. Show the inferred unit. If you auto-detected milliseconds, say so. Transparency prevents the next bug report.

Worked Example End-to-End

Input: 1697284005000

1. Digit count: 13 → inferred unit: milliseconds
2. Normalize: 1697284005000 ÷ 1000 = 1697284005 seconds
3. UTC conversion: 2023-10-14T15:46:45Z
4. Local display (UTC-4): 2023-10-14 11:46:45 EDT
5. Output label: "Input interpreted as milliseconds. UTC: 2023-10-14T15:46:45Z"

No ambiguity. No silent overflow. No wrong decade.

The One-Line Takeaway

When your Unix timestamp converter returns the wrong date for a millisecond value, the converter is not broken — it is making a different assumption than your data. Count the digits. Normalize to seconds. Convert in UTC. Label the unit. Do that every time, and the 1970 problem disappears for good.