{"record":{"id":"a63dbeecd56d7662","repo":"clockworklabs/SpacetimeDB","slug":"unsupported-uuid-version-version","errorCode":null,"errorMessage":"Unsupported UUID version: ${version}","messagePattern":"Unsupported UUID version: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/lib/uuid.ts","lineNumber":305,"sourceCode":"   * @returns A `UuidVersion`\n   * @throws {Error} If the version field is not recognized\n   */\n  getVersion(): UuidVersion {\n    const version = (this.toBytes()[6] >> 4) & 0x0f;\n\n    switch (version) {\n      case 4:\n        return 'V4';\n      case 7:\n        return 'V7';\n      default:\n        if (this == Uuid.NIL) {\n          return 'Nil';\n        }\n        if (this == Uuid.MAX) {\n          return 'Max';\n        }\n        throw new Error(`Unsupported UUID version: ${version}`);\n    }\n  }\n\n  /**\n   * Extract the monotonic counter from a UUIDv7.\n   *\n   * Intended for testing and diagnostics.\n   * Behavior is undefined if called on a non-V7 UUID.\n   *\n   * @returns 31-bit counter value\n   */\n  getCounter(): number {\n    const bytes = this.toBytes(); // big-endian, 16 bytes\n\n    const high = bytes[7]; // bits 30..23\n    const mid1 = bytes[9]; // bits 22..15\n    const mid2 = bytes[10]; // bits 14..7\n    const low = bytes[11] >>> 1; // bits 6..0","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/lib/uuid.ts#L287-L323","documentation":"Uuid.getVersion() reads the 4-bit version field (high nibble of byte 6) and only recognizes 4 ('V4') and 7 ('V7'), plus the Nil and Max all-zero/all-one sentinels. This SDK deliberately supports only the V4/V7/Nil/Max set, so any other version nibble (1, 2, 3, 5, 6, 8-15) throws.","triggerScenarios":"Calling getVersion() - directly or via logging/serialization code that uses it - on a Uuid.parse'd value produced by another generator: UUIDv1 (MAC/timestamp), v5 (name-based SHA-1), v6, or any non-RFC4122 variant value.","commonSituations":"Ingesting ids from the `uuid` npm package defaults (v4 is safe, v1/v5/v6 are not), from PostgreSQL uuid_generate_v1mc()/v5 extensions, or from third-party systems that emit v1/v5; storing foreign ids in a SpacetimeDB U128 column and calling getVersion on them.","solutions":["Only feed V4/V7 (or Nil/Max) values into Uuid; generate ids with Uuid.fromRandomBytesV4 / fromCounterV7 or uuid.v4()/v7()","Check the version nibble yourself before calling getVersion: (u.toBytes()[6] >> 4) & 0x0f must be 4 or 7","Wrap getVersion() in try-catch when the Uuid came from external, untrusted input"],"exampleFix":"// before\nconst u = Uuid.parse('6ec1bd26-8479-11ef-b3f2-325096b39f47'); // a v1 uuid\nconst v = u.getVersion(); // throws: Unsupported UUID version: 1\n\n// after\nconst ver = (u.toBytes()[6] >> 4) & 0x0f;\nconst v = ver === 4 || ver === 7 ? u.getVersion() : 'foreign';","handlingStrategy":"type-guard","validationCode":"const ver = (u.toBytes()[6] >> 4) & 0x0f;\nif (ver !== 4 && ver !== 7 && u.compareTo(Uuid.NIL) !== 0 && u.compareTo(Uuid.MAX) !== 0) {\n  // foreign uuid: do not call getVersion()\n}","typeGuard":"function isSupportedUuid(u: Uuid): boolean {\n  const ver = (u.toBytes()[6] >> 4) & 0x0f;\n  return (\n    ver === 4 ||\n    ver === 7 ||\n    u.compareTo(Uuid.NIL) === 0 ||\n    u.compareTo(Uuid.MAX) === 0\n  );\n}","tryCatchPattern":"try {\n  label = u.getVersion();\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unsupported UUID version')) {\n    label = 'foreign';\n  } else throw e;\n}","preventionTips":["Generate ids with Uuid.fromRandomBytesV4/fromCounterV7 so versions stay in the supported set","Treat getVersion() as fallible whenever the Uuid originated outside this SDK"],"tags":["uuid","version","compatibility","typescript"],"backgroundTag":"unsupported-uuid-version","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}