{"record":{"id":"5ac017e12aec02ac","repo":"clockworklabs/SpacetimeDB","slug":"unknown-uuid-version","errorCode":null,"errorMessage":"Unknown UUID version","messagePattern":"Unknown UUID version","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"crates/bindings-csharp/BSATN.Runtime/BSATN/Uuid.cs","lineNumber":218,"sourceCode":"    }\n\n    /// <summary>\n    /// Returns the <see cref=\"UuidVersion\"/> of this <see cref=\"Uuid\"/>.\n    ///\n    /// Throws <see cref=\"InvalidOperationException\"/> if the <see cref=\"Uuid\"/> version is unknown.\n    /// </summary>\n    public UuidVersion GetVersion()\n    {\n        var bytes = value.ToBytesBigEndian();\n        var version = (bytes[6] >> 4) & 0x0F;\n\n        return version switch\n        {\n            4 => UuidVersion.V4,\n            7 => UuidVersion.V7,\n            _ => this == Uuid.NIL ? UuidVersion.Nil\n            : this == Uuid.MAX ? UuidVersion.Max\n            : throw new InvalidOperationException(\"Unknown UUID version\"),\n        };\n    }\n\n    private static void GuidToBigEndianBytes(ReadOnlySpan<byte> guidBytes, Span<byte> be)\n    {\n        // Guid’s weird internal layout (mixed-endian)\n\n        // time_low (4 bytes) — little-endian → reverse\n        be[0] = guidBytes[3];\n        be[1] = guidBytes[2];\n        be[2] = guidBytes[1];\n        be[3] = guidBytes[0];\n\n        // time_mid (2 bytes) — little-endian\n        be[4] = guidBytes[5];\n        be[5] = guidBytes[4];\n\n        // time_hi_and_version (2 bytes) — little-endian","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-csharp/BSATN.Runtime/BSATN/Uuid.cs#L200-L236","documentation":"Uuid.GetVersion() decodes the version nibble (byte 6 high bits) and only recognizes 4 (random) and 7 (time-ordered), plus the special all-zero NIL and all-one MAX values. Any other 128-bit value - v1 time-based, v5 name-based, v6, v8, or a raw U128 that is not a UUID at all - throws InvalidOperationException.","triggerScenarios":"Constructing a Uuid from a Guid produced by external systems that emit v1/v5/v6/v8; wrapping an arbitrary U128/I128 database column in a Uuid and calling GetVersion(); parsing corrupted or truncated bytes.","commonSituations":"Migrating IDs from legacy systems using time-based v1 GUIDs (common on Windows/SQL Server); storing non-UUID 128-bit values in a column typed as Uuid; interop with Node/Python libs generating v6/v8.","solutions":["Check the version nibble yourself before calling GetVersion: (value.ToBytesBigEndian()[6] >> 4) must be 4 or 7 (or the value equals Uuid.NIL / Uuid.MAX)","Only produce IDs via the library's own generators (Uuid.RandomV4 / FromCounterV7) so versions stay supported","If the column genuinely holds arbitrary U128s, use SpacetypeDB's U128 type instead of Uuid","Re-key legacy v1/v5 identifiers to v4/v7 at import time"],"exampleFix":"// before\nvar u = new Uuid(U128.FromBytesBigEndian(rawBytes));\nvar v = u.GetVersion(); // throws for v1/v5/v6/v8/raw data\n\n// after\nstatic UuidVersion SafeVersion(Uuid u) =>\n    u == Uuid.NIL ? UuidVersion.Nil\n    : u == Uuid.MAX ? UuidVersion.Max\n    : (u.ToBytesBigEndian()[6] >> 4) switch { 4 => UuidVersion.V4, 7 => UuidVersion.V7, _ => (UuidVersion)(-1) };","handlingStrategy":"validation","validationCode":"static bool IsSupportedUuid(Uuid u)\n{\n    if (u == Uuid.NIL || u == Uuid.MAX) return true;\n    var v = (u.ToBytesBigEndian()[6] >> 4) & 0x0F;\n    return v is 4 or 7;\n}\n\nif (IsSupportedUuid(id)) { var ver = id.GetVersion(); }","typeGuard":null,"tryCatchPattern":"UuidVersion ver;\ntry { ver = id.GetVersion(); }\ncatch (InvalidOperationException) { ver = default; /* treat as unknown/opaque */ }","preventionTips":["Generate IDs only through this library so version nibbles stay 4 or 7","Do not wrap arbitrary U128 column values in Uuid if you plan to query versions","Re-key imported v1/v5/v6/v8 identifiers to v4/v7 at migration time"],"tags":["csharp","uuid","version-mismatch","uuidv4","uuidv7"],"backgroundTag":"unsupported-uuid-version","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}