{"record":{"id":"b1a9753608d79890","repo":"clockworklabs/SpacetimeDB","slug":"invalid-hex-uuid","errorCode":null,"errorMessage":"Invalid hex UUID","messagePattern":"Invalid hex UUID","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/lib/uuid.ts","lineNumber":225,"sourceCode":"\n  /**\n   * Parse a UUID from a string representation.\n   *\n   * @param s - UUID string\n   * @returns Parsed UUID\n   * @throws {Error} If the string is not a valid UUID\n   *\n   * @example\n   * ```ts\n   * const s = \"01888d6e-5c00-7000-8000-000000000000\";\n   * const uuid = Uuid.parse(s);\n   *\n   * console.assert(uuid.toString() === s);\n   * ```\n   */\n  static parse(s: string): Uuid {\n    const hex = s.replace(/-/g, '');\n    if (hex.length !== 32) throw new Error('Invalid hex UUID');\n\n    let v = 0n;\n    for (let i = 0; i < 32; i += 2) {\n      v = (v << 8n) | BigInt(parseInt(hex.slice(i, i + 2), 16));\n    }\n    return new Uuid(v);\n  }\n\n  /** Convert to hex string without a 0x prefix. */\n  toHexString(): string {\n    return u128ToHexString(this.asBigInt());\n  }\n\n  /** Convert to string (hyphenated form). */\n  toString(): string {\n    const hex = this.toHexString();\n\n    // Format as 8-4-4-4-12","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/6dee26c6efc2856793e12b148a59742964f5d783/crates/bindings-typescript/src/lib/uuid.ts#L207-L243","documentation":"Uuid.parse strips every '-' from the input and then requires the remainder to be exactly 32 characters. The 'Invalid hex UUID' error is this dash-stripped length check: wrong digit count, brace/URN wrappers, 0x prefixes, or extra characters all change the length and fail. Note the parser checks length, not character legality, so do not rely on it to validate hex.","triggerScenarios":"Uuid.parse('not-a-uuid'); Uuid.parse('01888d6e-5c00-7000-8000-0000000000') (31 hex digits after the 12 hex digits of the last group are short by one); strings like '{01888d6e-...}' or 'urn:uuid:...' that add non-hex characters; values with trailing whitespace or a 0x prefix.","commonSituations":"Forwarding user input, URL query params, or database columns straight into parse; mixing canonical hyphenated and compact 32-char formats; UUIDs received from other systems wrapped in braces or URN prefixes.","solutions":["Validate with a canonical UUID regex before parsing (see type guard)","Normalize the input first: trim whitespace, strip surrounding braces and 'urn:uuid:' prefixes","Only call parse on values produced by Uuid.toString() or a known UUID source"],"exampleFix":"// before\nconst id = Uuid.parse(rawUserInput); // may throw\n\n// after\nconst id = isUuidString(rawUserInput) ? Uuid.parse(rawUserInput) : fallbackForInvalidId(rawUserInput);","handlingStrategy":"type-guard","validationCode":"const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;\nif (!UUID_RE.test(candidate)) {\n  throw new Error(`not a canonical UUID: ${candidate}`);\n}\nconst id = Uuid.parse(candidate);","typeGuard":"const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;\nfunction isUuidString(s: unknown): s is string {\n  return typeof s === 'string' && UUID_RE.test(s);\n}","tryCatchPattern":"try {\n  const id = Uuid.parse(candidate);\n} catch (e) {\n  if (e instanceof Error && e.message === 'Invalid hex UUID') {\n    // treat as bad input: reject, re-prompt, or skip the record\n  }\n  throw e;\n}","preventionTips":["Validate untrusted strings with the regex guard before parse; parse only checks dash-stripped length","Normalize inputs: trim, strip '{', '}' and 'urn:uuid:' prefixes","Round-trip your own IDs via Uuid.toString() so the format is always canonical"],"tags":["uuid","typescript","parsing","input-validation"],"backgroundTag":"invalid-uuid-format","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"}