{"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/6dee26c6efc2856793e12b148a59742964f5d783/crates/bindings-typescript/src/lib/uuid.ts#L287-L323","documentation":"The UUID version classifier only knows version 4, version 7, and the exact sentinels Uuid.NIL (all zero bits) and Uuid.MAX (all one bits). Any other version nibble — v1, v3, v5, v6, or arbitrary 128-bit data that is not a structured UUID — throws 'Unsupported UUID version'.","triggerScenarios":"Calling the version classification on a Uuid parsed from a v1/v3/v5/v6 string (e.g. from the uuid npm package), or on a Uuid constructed from an arbitrary 128-bit BigInt used as a generic ID.","commonSituations":"Interoperating with third-party systems that emit time-based (v1) or name-based (v3/v5) UUIDs; storing opaque 128-bit keys in a UUID-typed column and then asking for their version; mixing output of multiple UUID libraries.","solutions":["Branch on the version nibble yourself and only classify values you know are v4/v7 (or NIL/MAX)","Normalize foreign UUIDs at the system boundary: keep the bytes but stop asking for their version","If you control generation, emit only v4 or v7 so classification is always defined"],"exampleFix":"// before\nconst label = uuidFromExternalSystem.classifyVersion(); // throws for v1\n\n// after\nif (uuid == Uuid.NIL || uuid == Uuid.MAX) { /* sentinel */ }\nelse if (isSupportedUuidVersion(uuid)) { const label = uuid.classifyVersionSafe(); }","handlingStrategy":"type-guard","validationCode":"const version = Number((u.asBigInt() >> 76n) & 0xfn);\nif (!(u == Uuid.NIL || u == Uuid.MAX || version === 4 || version === 7)) {\n  // do not classify; handle as opaque id\n}","typeGuard":"function uuidVersionOf(u: Uuid): number {\n  return Number((u.asBigInt() >> 76n) & 0xfn);\n}\nfunction isClassifiableUuid(u: Uuid): boolean {\n  return u == Uuid.NIL || u == Uuid.MAX || [4, 7].includes(uuidVersionOf(u));\n}","tryCatchPattern":"try {\n  const label = uuid.classify();\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unsupported UUID version')) {\n    // foreign or unstructured id: skip classification\n  }\n  throw e;\n}","preventionTips":["Standardize on v4/v7 at every system boundary that feeds this library","Treat v1/v3/v5/v6 inputs as opaque 128-bit keys and never ask for their version","Check the version nibble before calling the classifier on external data"],"tags":["uuid","typescript","version-mismatch"],"backgroundTag":"unsupported-uuid-version","analyzedSha":"6dee26c6efc2856793e12b148a59742964f5d783","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}