clockworklabs/SpacetimeDB · error · Error

Unsupported UUID version

Error message

Unsupported UUID version: ${version}

What it means

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'.

Solutions

1. Branch on the version nibble yourself and only classify values you know are v4/v7 (or NIL/MAX)
2. Normalize foreign UUIDs at the system boundary: keep the bytes but stop asking for their version
3. If you control generation, emit only v4 or v7 so classification is always defined

Example fix

// before
const label = uuidFromExternalSystem.classifyVersion(); // throws for v1

// after
if (uuid == Uuid.NIL || uuid == Uuid.MAX) { /* sentinel */ }
else if (isSupportedUuidVersion(uuid)) { const label = uuid.classifyVersionSafe(); }

const version = Number((u.asBigInt() >> 76n) & 0xfn);
if (!(u == Uuid.NIL || u == Uuid.MAX || version === 4 || version === 7)) {
  // do not classify; handle as opaque id
}

function uuidVersionOf(u: Uuid): number {
  return Number((u.asBigInt() >> 76n) & 0xfn);
}
function isClassifiableUuid(u: Uuid): boolean {
  return u == Uuid.NIL || u == Uuid.MAX || [4, 7].includes(uuidVersionOf(u));
}

try {
  const label = uuid.classify();
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported UUID version')) {
    // foreign or unstructured id: skip classification
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• `fromCounterV7` requires `randomBytes.length == 4`
• `fromCounterV7` `timestamp` before unix epoch
• `fromCounterV7` uuid `counter` must be non-negative
• Invalid hex UUID
• Argument must be a Uuid

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/a63dbeecd56d7662. Report an issue: GitHub.

Appendix: source

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

   * @returns A `UuidVersion`
   * @throws {Error} If the version field is not recognized
   */
  getVersion(): UuidVersion {
    const version = (this.toBytes()[6] >> 4) & 0x0f;

    switch (version) {
      case 4:
        return 'V4';
      case 7:
        return 'V7';
      default:
        if (this == Uuid.NIL) {
          return 'Nil';
        }
        if (this == Uuid.MAX) {
          return 'Max';
        }
        throw new Error(`Unsupported UUID version: ${version}`);
    }
  }

  /**
   * Extract the monotonic counter from a UUIDv7.
   *
   * Intended for testing and diagnostics.
   * Behavior is undefined if called on a non-V7 UUID.
   *
   * @returns 31-bit counter value
   */
  getCounter(): number {
    const bytes = this.toBytes(); // big-endian, 16 bytes

    const high = bytes[7]; // bits 30..23
    const mid1 = bytes[9]; // bits 22..15
    const mid2 = bytes[10]; // bits 14..7
    const low = bytes[11] >>> 1; // bits 6..0

View on GitHub (pinned to 6dee26c6ef)