Guide
When a Timestamp Looks Right but the Timezone Is Wrong
Learn how a correct numeric timestamp can still produce wrong business time when timezone context is missing.
A timestamp value can be technically valid while the displayed hour is still wrong for users. The issue is usually timezone interpretation, not the raw number.
Know what a Unix timestamp does and does not include
Unix timestamps represent elapsed time from epoch and do not contain timezone labels.
Timezone is applied later when formatting for humans.
Map each layer in the time pipeline
List storage timezone, API serialization format, and frontend display timezone.
Many bugs come from one implicit local conversion in the middle.
Compare UTC output with user-local output
Seeing both views side by side reveals where the shift appears.
If UTC matches expected event but local output does not, formatting rules need review.
- Check locale formatting settings.
- Verify timezone passed to formatter utilities.
- Test with users in another region.
Watch daylight saving boundaries
DST changes can create repeated or missing local hours.
Run test timestamps around transition dates to catch hidden edge cases.
Write timezone rules in product docs
State whether each feature shows UTC, account timezone, or viewer-local time.
Clear display rules reduce support confusion and repeat bug reports.
Common situations
- Event time is off by a fixed number of hours.
- Server logs look correct but UI schedule is wrong.
- Support tickets mention wrong local appointment time.
- DST transitions cause one-hour surprises.
A valid timestamp still needs timezone context
Confirm where the time was created, how it was transported, and how it is finally rendered.