Unix Timestamps: Seconds, Milliseconds, and Timezone Bugs

The most common Unix timestamp bug comes from conflating seconds and milliseconds. Unix time was originally defined in seconds, but JavaScript's Date.now() and many modern APIs and databases return milliseconds by default. A current timestamp in seconds is a 10-digit number (e.g., 1,700,000,000). The same moment in milliseconds is a 13-digit number (e.g., 1,700,000,000,000). If you store or process a millisecond timestamp as if it were in seconds, you get a date approximately 33,000 years in the future.

This bug appears in several common scenarios. When reading timestamps from a JavaScript frontend and passing them to a Python or Java backend that expects seconds, any value that looks 'big' without units is ambiguous. When inserting into a database column typed as TIMESTAMP, the database may interpret 13-digit values as seconds and store a nonsensical date. When reading from an API that returns milliseconds and comparing against a database column that stores seconds, comparison logic will always be wrong.

The fix is simple but requires discipline: always document the unit explicitly in variable names and database schemas. Name columns created_at_ms or created_at_seconds, not just created_at when the unit might be ambiguous. Always convert to a known unit as close to the data source as possible and propagate only the canonical unit through the rest of your codebase. A helper function that takes a raw timestamp and returns a standardized seconds value — after detecting or asserting the input unit — is worth writing once and using everywhere.

Unix timestamps are inherently UTC by definition — they count from the UTC epoch. But application code frequently introduces local time implicitly. In Python, datetime.now() returns local time, while datetime.utcnow() returns UTC. In Java, new Date() returns local time by default in older code. In JavaScript, new Date().toISOString() is UTC, but new Date().toString() is local time. If you construct a timestamp from local time components without explicitly specifying UTC, you store the wrong moment.

This category of bug is particularly insidious because it only becomes visible when users in different timezones interact with the same data, or when servers are moved to different regions. A cron job that was tested in IST may run at the wrong time when deployed to a UTC server. An order created at 11:30 PM IST might be stored as 2024-01-15 00:00:00 UTC when the developer intended 2024-01-14. Report filters for 'today's orders' based on dates may cut off or include the wrong records depending on the server timezone.

The correct practice is to store all timestamps as UTC at the database level and convert to local time only at the presentation layer — as close to the user as possible. Use database column types that store timezone information (TIMESTAMPTZ in PostgreSQL, for example) or always store plain integers (epoch seconds in UTC). If your database does not support timezone-aware types, document explicitly in your schema and application code that all timestamps are UTC, and enforce this in code review.

Converting a UTC timestamp to the user's local time for display is a distinct operation from storing it, and it requires knowing the user's timezone — not just an offset. Timezones and UTC offsets are not the same thing. India's IST is UTC+5:30 with no daylight saving time. The US Eastern timezone is UTC-5 in winter and UTC-4 in summer. Using a fixed offset (+05:30, -05:00) instead of a named timezone identifier (Asia/Kolkata, America/New_York) means your application will display incorrect times during daylight saving transitions for US, European, and Australian users.

The safest approach is to use IANA timezone names and rely on a well-maintained timezone library to handle offset changes. In JavaScript, the Intl.DateTimeFormat API with a timeZone option handles this correctly in modern browsers. In Python, the zoneinfo module (Python 3.9+) or pytz library provides correct IANA timezone support. In Java, ZoneId from java.time handles it correctly. Never hard-code UTC offsets for timezones that observe daylight saving time.

For an Indian audience specifically: if all your users are in India, IST (UTC+5:30) is fixed year-round and using the fixed offset is safe. But if you are serving international users or your system interacts with international APIs (payment gateways, AWS timestamps, Google Cloud logs), always normalize to UTC in storage and log timestamps in ISO 8601 format (e.g., 2024-01-15T17:00:00Z) so that any reader can unambiguously convert to their local time.

When debugging a timestamp-related issue in production, an epoch converter is often the fastest way to verify what a raw number actually represents. If your error log shows a request at timestamp 1706803200 and you want to know whether that is in the expected range, converting it to a human-readable date immediately tells you if the value is plausible, in the wrong timezone, or off by orders of magnitude due to a seconds/milliseconds mix-up.

Epoch converters are also useful when reading API documentation. When an API says it returns 'a Unix timestamp in milliseconds since epoch,' you can verify this by converting a sample response value and checking if it matches the expected date. This takes seconds and catches integration bugs before they reach production. Some APIs return dates in formats like '20240115T170000Z' or '2024-01-15T17:00:00.000+05:30' rather than epoch time — a converter that handles multiple formats helps you normalize these as well.

Finally, epoch converters are useful for constructing query parameters when calling APIs that accept timestamp ranges. If you want to fetch all records created after January 1, 2024 UTC, converting that date to its epoch representation (1704067200 in seconds, 1704067200000 in milliseconds) in advance saves you from mental arithmetic that is easy to get wrong. Use the converter, double-check the output, then paste the value into your API call or SQL query.