{"record":{"id":"a0714b5e50cecb4a","repo":"clockworklabs/SpacetimeDB","slug":"invalid-uuid-must-be-between-0-and-max-uuid-bigi","errorCode":null,"errorMessage":"Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`","messagePattern":"Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/lib/uuid.ts","lineNumber":77,"sourceCode":"   * );\n   * ```\n   */\n  static readonly MAX = new Uuid(Uuid.MAX_UUID_BIGINT);\n\n  /**\n   * Create a UUID from a raw 128-bit value.\n   *\n   * @param u - Unsigned 128-bit integer\n   * @throws {Error} If the value is outside the valid UUID range\n   */\n  constructor(u: bigint) {\n    // Coerce so callers who arrive via JSON (where bigint precision is\n    // lost) hit the range check rather than a cryptic `Cannot mix\n    // BigInt and other types` error.\n    const v = coerceToBigInt(u, 'Uuid');\n    // Must fit in exactly 16 bytes\n    if (v < 0n || v > Uuid.MAX_UUID_BIGINT) {\n      throw new Error('Invalid UUID: must be between 0 and `MAX_UUID_BIGINT`');\n    }\n    this.__uuid__ = v;\n  }\n\n  /**\n   * Create a UUID `v4` from explicit random bytes.\n   *\n   * This method assumes the bytes are already sufficiently random.\n   * It only sets the appropriate bits for the UUID version and variant.\n   *\n   * @param bytes - Exactly 16 random bytes\n   * @returns A UUID `v4`\n   * @throws {Error} If `bytes.length !== 16`\n   *\n   * @example\n   * ```ts\n   * const randomBytes = new Uint8Array(16);\n   * const uuid = Uuid.fromRandomBytesV4(randomBytes);","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/lib/uuid.ts#L59-L95","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate 0n <= v && v <= Uuid.MAX_UUID_BIGINT before constructing","Build the value with uint8ArrayToU128 on the 16 source bytes instead of hand-rolled arithmetic","Compare against the library's exported Uuid.MAX_UUID_BIGINT rather than a hand-typed constant"],"exampleFix":"// before\nconst id = new Uuid(computed); // computed drifted past 2^128-1 -> throws\n\n// after\nif (computed < 0n || computed > Uuid.MAX_UUID_BIGINT) {\n  throw new RangeError(`uuid value out of range: ${computed}`);\n}\nconst id = new Uuid(computed);","handlingStrategy":"validation","validationCode":"function isValidUuidValue(v: bigint): boolean {\n  return v >= 0n && v <= 0xffff_ffff_ffff_ffff_ffff_ffff_ffff_ffffn; // 2^128 - 1\n}\n// Prefer the library constant: v >= 0n && v <= Uuid.MAX_UUID_BIGINT","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build uuid bigints from bytes with uint8ArrayToU128 instead of hand arithmetic","Range-check before constructing when values come from other id schemes","Use the exported Uuid.MAX_UUID_BIGINT constant rather than re-typing 2^128-1"],"tags":["uuid","bigint","range","validation","javascript"],"backgroundTag":"uuid-out-of-range","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}