Milliseconds vs seconds vs microseconds: finding the one-unit bug in logs
A practical timestamp debugging guide for spotting unit mistakes quickly when values in logs or APIs look almost right.
Tip
Inspect the current certificate, key, token, or endpoint output before changing deployment config; stale artifacts make fixes misleading.
The one-unit bug is one of the most common time bugs because the number still looks plausible. It is just off by three or six zeroes, which is enough to throw tokens, TTLs, and log analysis into chaos.
The good news is that unit bugs are usually easy to detect once you stop reading the number as a mystery and start reading its magnitude.
Summary
Definition: Epoch values can be expressed in seconds, milliseconds, or microseconds, and the unit must be known before the number can be interpreted correctly.
Why it matters: A unit mismatch can shift a timestamp by decades or collapse a valid window into immediate expiry.
Pitfall: Because the number often looks realistic, people sometimes debug the wrong layer before checking the unit.
Magnitude is your first clue
A ten-digit Unix value often suggests seconds for modern dates. Thirteen digits often suggests milliseconds. Sixteen digits often points to microseconds. That is not a perfect rule, but it is a fast and useful first screen when you inherit a raw timestamp from logs or API output.
Once you suspect the unit, convert it immediately instead of continuing to reason in raw numbers.
Unit bugs spread across layers
A frontend may send milliseconds to a backend that expects seconds. A JWT library may produce seconds while logs show milliseconds. A database may store higher precision than the API contract exposes. These are not separate mysteries. They are one normalization problem wearing different clothes.
- Count digits before discussing meaning.
- Normalize the unit before comparing across systems.
- Document the unit in the contract instead of leaving it implicit.
Why a tiny converter is so useful
A timestamp converter earns its place by turning suspicion into confirmation quickly. When the same value is shown as seconds, milliseconds, and human-readable time side by side, the bug often resolves itself.
Quick example
Use this when a timestamp seems to point impossibly far into the future or past.
What to notice: This is a quick heuristic, not a substitute for the actual system contract.
10 digits -> usually seconds
13 digits -> usually milliseconds
16 digits -> often microseconds
Practical check
- Count digits before doing anything else.
- Normalize the value into one explicit unit across systems.
- Write the unit into the API or log contract so the next person does not guess.
FAQ
Are digit counts always enough to know the unit?
No, but they are an excellent first clue for modern timestamps.
Can a unit bug break JWT validation?
Yes. Time-window claims are extremely sensitive to unit mistakes.
Developer workflow
Use this guide as an operations checklist before changing certificates, tokens, DNS, or deployment settings.
- Inspect the current artifact or endpoint output before making changes.
- Change one variable at a time so a failed verification has a narrow cause.
- Keep the rollback value, expiry, and verification command in the same runbook entry.
1. current deployed artifact
2. single config or key change
3. verify endpoint/client behavior
4. record rollback and expiry details