clockworklabs/SpacetimeDB · error · Error

Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`

Error message

Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`

What it means

new Uuid(bigint) first coerces via coerceToBigInt (so callers arriving via JSON hit the range check rather than a cryptic BigInt mixing error), then requires the value to fit in exactly 16 unsigned bytes: 0 <= v <= Uuid.MAX_UUID_BIGINT (2^128 - 1). Outside that range a UUID is not representable, so it throws.

Source

Thrown at crates/bindings-typescript/src/lib/uuid.ts:77

   * );
   * ```
   */
  static readonly MAX = new Uuid(Uuid.MAX_UUID_BIGINT);

  /**
   * Create a UUID from a raw 128-bit value.
   *
   * @param u - Unsigned 128-bit integer
   * @throws {Error} If the value is outside the valid UUID range
   */
  constructor(u: bigint) {
    // Coerce so callers who arrive via JSON (where bigint precision is
    // lost) hit the range check rather than a cryptic `Cannot mix
    // BigInt and other types` error.
    const v = coerceToBigInt(u, 'Uuid');
    // Must fit in exactly 16 bytes
    if (v < 0n || v > Uuid.MAX_UUID_BIGINT) {
      throw new Error('Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`');
    }
    this.__uuid__ = v;
  }

  /**
   * Create a UUID `v4` from explicit random bytes.
   *
   * This method assumes the bytes are already sufficiently random.
   * It only sets the appropriate bits for the UUID version and variant.
   *
   * @param bytes - Exactly 16 random bytes
   * @returns A UUID `v4`
   * @throws {Error} If `bytes.length !== 16`
   *
   * @example
   * ```ts
   * const randomBytes = new Uint8Array(16);
   * const uuid = Uuid.fromRandomBytesV4(randomBytes);

View on GitHub (pinned to 524b4487d9)

Solutions

1. Validate 0n <= v && v <= Uuid.MAX_UUID_BIGINT before constructing
2. Build the value with uint8ArrayToU128 on the 16 source bytes instead of hand-rolled arithmetic
3. Compare against the library's exported Uuid.MAX_UUID_BIGINT rather than a hand-typed constant

Example fix

// before
const id = new Uuid(computed); // computed drifted past 2^128-1 -> throws

// after
if (computed < 0n || computed > Uuid.MAX_UUID_BIGINT) {
  throw new RangeError(`uuid value out of range: ${computed}`);
}
const id = new Uuid(computed);

function isValidUuidValue(v: bigint): boolean {
  return v >= 0n && v <= 0xffff_ffff_ffff_ffff_ffff_ffff_ffff_ffffn; // 2^128 - 1
}
// Prefer the library constant: v >= 0n && v <= Uuid.MAX_UUID_BIGINT

When it happens

Trigger: new Uuid(-1n); a value shifted or multiplied past 2^128-1 due to a bytes-to-bigint math error; or a JSON number that lost precision and became huge.

Common situations: BigInt arithmetic bugs (wrong shift width, sign errors); interoperating with signed 128-bit or 256-bit id schemes; converting byte arrays to bigint by hand instead of using the provided converters.

Related errors

• UUID v4 requires 16 bytes
• Timestamp is outside of the representable range of JS's Date
• Timestamp is outside of the representable range for ISO stri
• Uint8Array is not 16 bytes long: ${array}
• Uint8Array is not 32 bytes long: [${array}]

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/a0714b5e50cecb4a. Report an issue: GitHub.