Definition

UUID overflow refers to the condition where a numeric field inside a time-based UUID — most commonly the timestamp or the per-millisecond monotonic counter — reaches its maximum representable value and would wrap around on the next increment.

UUID formats that embed timestamps are the only versions subject to overflow. UUID v4 is entirely random and has no timestamp field, so it is not affected. UUID v7 and the now-deprecated UUID v1 both carry timestamp fields with defined upper bounds.

Understanding overflow is useful for capacity planning, for evaluating the long-term viability of an ID scheme, and for writing correct generator code.

Timestamp overflow in UUID v7

UUID v7 stores a 48-bit Unix millisecond timestamp in its most significant bits. The maximum value is:

2⁴⁸ − 1 = 281,474,976,710,655 ms after Unix epoch (1970-01-01T00:00:00Z)
         ≈ year 10,889

This is not a practical concern. For comparison, the Y2K38 problem (32-bit Unix second overflow) occurs in 2038, which is far sooner and affects many more systems.

The 48-bit field in UUID v7 also means a maximum timestamp resolution of 1 millisecond — sufficient for all practical ordering requirements. If sub-millisecond ordering is required, the monotonic counter provides 12 additional bits of ordering within each millisecond.

Monotonic counter overflow

The counter overflow is the more operationally relevant overflow scenario. The sequence field in UUID v7 is 12 bits wide:

Counter range: 0 – 4,095  (2¹² − 1)
Maximum rate:  4,096 UUIDs per millisecond from a single generator

When a generator exhausts all 4,096 counter values within a single millisecond, it has two conforming options per RFC 9562 §6.2:

  1. Block — wait until the system clock advances to the next millisecond, then reset the counter with a new random seed and continue.
  2. Borrow a future millisecond — increment the timestamp by 1 and reset the counter, effectively generating UUIDs that appear to belong to the next millisecond. This keeps throughput smooth at the cost of slightly advancing the logical clock.
// Pseudocode: counter overflow handling (borrow strategy)
if (counter > 0xFFF) {
  // Borrow one millisecond from the future
  timestampMs += 1;
  counter = 0;
}

At 4,096 UUIDs/ms the generator is sustaining over 4 billion UUIDs per second — a rate no single-process application reaches in practice. Counter overflow is therefore an edge case for batch-generation benchmarks, not normal operational workloads.

UUID v1 timestamp comparison

UUID v1 uses a fundamentally different timestamp encoding:

FieldUUID v1UUID v7
Epoch15 October 1582Unix epoch (1970-01-01)
Resolution100-nanosecond intervals1 millisecond
Bit width60 bits48 bits
Overflow year~5236~10889

Despite the 60-bit field, UUID v1 overflows sooner because 100-nanosecond resolution exhausts the field faster than millisecond resolution. UUID v1 is deprecated by RFC 9562 — use UUID v7 for all new time-ordered UUID requirements.

Detecting overflow in generator code

A well-written UUID v7 generator should guard against both clock rollback and counter overflow:

let lastMs   = 0;
let counter  = 0;

function nextUuidV7Timestamp(): { ms: number; seq: number } {
  let ms = Date.now();

  if (ms < lastMs) {
    // Clock rollback — freeze to last known time
    ms = lastMs;
  }

  if (ms === lastMs) {
    counter = (counter + 1) & 0xFFF; // 12-bit mask
    if (counter === 0) {
      // Counter wrapped — borrow next millisecond
      ms = lastMs + 1;
    }
  } else {
    // New millisecond — reset counter with random low bits
    counter = Math.floor(Math.random() * 0x1000) & 0xFFF;
  }

  lastMs = ms;
  return { ms, seq: counter };
}

Generate overflow-safe UUIDs with the UUID v7 generator.

Frequently asked questions

When will UUID v7 timestamps overflow?

UUID v7 encodes a 48-bit Unix millisecond timestamp. The maximum value is 2⁴⁸ − 1 milliseconds after the Unix epoch, which corresponds to approximately the year 10889. No production system will encounter a v7 timestamp overflow — it is a theoretical limit, not an operational concern. See UUID Epoch for details on how the timestamp field is structured.

What happens when a UUID v7 monotonic counter overflows?

The monotonic counter in UUID v7 is 12 bits wide, allowing 4,096 values per millisecond. When it reaches 4,095, a conforming generator must either block until the clock advances to the next millisecond, or borrow one millisecond from the future timestamp (increment the timestamp by 1 and reset the counter). The uuid npm package blocks until the next millisecond tick. Borrowing future timestamps is permitted by RFC 9562 §6.2.

Does UUID v1 have a closer overflow date than UUID v7?

Yes. UUID v1 uses a 60-bit timestamp counting 100-nanosecond intervals since 15 October 1582 (the Gregorian epoch). That 60-bit field overflows around the year 5236 — still thousands of years away, but structurally closer than v7's year 10889. UUID v1 is also deprecated by RFC 9562 in favour of UUID v7 for new systems.

Can a clock rollback cause UUID overflow or duplication?

A clock rollback does not cause overflow, but it can cause UUID v7 generators to produce out-of-order or duplicate timestamps. Robust generators detect rollbacks and either freeze output until the clock catches up, or fall back to incrementing the last known timestamp. The monotonic counter pattern in RFC 9562 §6.2 is designed specifically to tolerate small clock regressions.