clockworklabs/SpacetimeDB · error · Error

Unsupported UUID version: ${version}

Error message

Unsupported UUID version: ${version}

What it means

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.

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 524b4487d9)

Solutions

1. Only feed V4/V7 (or Nil/Max) values into Uuid; generate ids with Uuid.fromRandomBytesV4 / fromCounterV7 or uuid.v4()/v7()
2. Check the version nibble yourself before calling getVersion: (u.toBytes()[6] >> 4) & 0x0f must be 4 or 7
3. Wrap getVersion() in try-catch when the Uuid came from external, untrusted input

Example fix

// before
const u = Uuid.parse('6ec1bd26-8479-11ef-b3f2-325096b39f47'); // a v1 uuid
const v = u.getVersion(); // throws: Unsupported UUID version: 1

// after
const ver = (u.toBytes()[6] >> 4) & 0x0f;
const v = ver === 4 || ver === 7 ? u.getVersion() : 'foreign';

const ver = (u.toBytes()[6] >> 4) & 0x0f;
if (ver !== 4 && ver !== 7 && u.compareTo(Uuid.NIL) !== 0 && u.compareTo(Uuid.MAX) !== 0) {
  // foreign uuid: do not call getVersion()
}

function isSupportedUuid(u: Uuid): boolean {
  const ver = (u.toBytes()[6] >> 4) & 0x0f;
  return (
    ver === 4 ||
    ver === 7 ||
    u.compareTo(Uuid.NIL) === 0 ||
    u.compareTo(Uuid.MAX) === 0
  );
}

try {
  label = u.getVersion();
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported UUID version')) {
    label = 'foreign';
  } else throw e;
}

When it happens

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

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

Related errors

• `fromCounterV7` requires `randomBytes.length == 4`
• `fromCounterV7` uuid `counter` must be non-negative
• Invalid hex UUID
• Module code was generated with an incompatible version of th
• metadata.toml indicates that you are running {relation} data

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