{"record":{"id":"ed583e37f07010ea","repo":"ramsey/uuid","slug":"the-byte-string-received-does-not-conform-to-the-r","errorCode":null,"errorMessage":"The byte string received does not conform to the RFC 9562 (formerly RFC 4122) or Microsoft Corporation variants","messagePattern":"The byte string received does not conform to the RFC 9562 \\(formerly RFC 4122\\) or Microsoft Corporation variants","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Guid/Fields.php","lineNumber":70,"sourceCode":"    use VersionTrait;\n\n    /**\n     * @param string $bytes A 16-byte binary string representation of a UUID\n     *\n     * @throws InvalidArgumentException if the byte string is not exactly 16 bytes\n     * @throws InvalidArgumentException if the byte string does not represent a GUID\n     * @throws InvalidArgumentException if the byte string does not contain a valid version\n     */\n    public function __construct(private string $bytes)\n    {\n        if (strlen($this->bytes) !== 16) {\n            throw new InvalidArgumentException(\n                'The byte string must be 16 bytes long; received ' . strlen($this->bytes) . ' bytes',\n            );\n        }\n\n        if (!$this->isCorrectVariant()) {\n            throw new InvalidArgumentException(\n                'The byte string received does not conform to the RFC 9562 (formerly RFC 4122) '\n                . 'or Microsoft Corporation variants',\n            );\n        }\n\n        if (!$this->isCorrectVersion()) {\n            throw new InvalidArgumentException('The byte string received does not contain a valid version');\n        }\n    }\n\n    public function getBytes(): string\n    {\n        return $this->bytes;\n    }\n\n    public function getTimeLow(): Hexadecimal\n    {\n        // Swap the bytes from little endian to network byte order.","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Guid/Fields.php#L52-L88","documentation":"When ramsey/uuid builds a Guid from 16 bytes, Guid\\Fields validates the variant bits. After the little-endian swap, the top bits of clock_seq_hi_and_reserved (first character of the string's 4th group) must be 10xx (RFC 9562 variant, hex 8-b) or 110x (Microsoft variant, hex c-d); 0xxx (NCS/reserved) and 111x (future reserved) variants are rejected, except for the all-zero nil and all-f max UUIDs which bypass the check.","triggerScenarios":"Decoding 16 bytes that are not a real GUID: Guid::fromBytes($bytes) or a custom codec where the variant octet starts with hex 0-7, e, or f. Example: Guid::fromBytes(hex2bin(str_repeat('f', 32))) throws this because the variant bits read 1111 (future).","commonSituations":"Converting arbitrary 16-byte identifiers (hashes, rowids, encryption output) to Guid; corrupted binary from external systems; hand-built test fixtures with random variant bits.","solutions":["Validate the variant bits before converting: first byte of the 4th group must be hex 8-b (RFC 9562) or c-d (Microsoft)","Use Guid::fromString()/fromBytes() on trusted GUID data only, and catch UnableToBuildUuidException when parsing untrusted input","If the value is a generic 128-bit identifier, keep it as a Hexadecimal instead of forcing it into a Guid"],"exampleFix":"// before\n$guid = \\Ramsey\\Uuid\\Guid\\Guid::fromBytes($arbitraryBytes);\n\n// after\n$variantNibble = hexdec(bin2hex($arbitraryBytes[8])) >> 4;\nif ($variantNibble < 0x8 || $variantNibble > 0xd) {\n    throw new InvalidArgumentException('Not a GUID-variant value');\n}\n$guid = \\Ramsey\\Uuid\\Guid\\Guid::fromBytes($arbitraryBytes);","handlingStrategy":"validation","validationCode":"$nibble = hexdec(bin2hex($bytes[8])) >> 4; // after little-endian context is settled\n// RFC 9562: 0x8-0xb, Microsoft: 0xc-0xd\nif ($nibble < 0x8 || $nibble > 0xd) {\n    throw new InvalidArgumentException('Not a GUID-variant 128-bit value');\n}","typeGuard":"function isGuidVariantBytes(string $bytes): bool\n{\n    if (strlen($bytes) !== 16) {\n        return false;\n    }\n    $n = hexdec(bin2hex($bytes[8])) >> 4;\n    return ($n >= 0x8 && $n <= 0xd)\n        || $bytes === str_repeat(\"\\x00\", 16)\n        || $bytes === str_repeat(\"\\xff\", 16);\n}","tryCatchPattern":"try {\n    $guid = \\Ramsey\\Uuid\\Guid\\Guid::fromBytes($bytes);\n} catch (\\Ramsey\\Uuid\\Exception\\UnableToBuildUuidException $e) {\n    if (str_contains($e->getMessage(), 'variants')) {\n        // value is not a real GUID; treat as opaque 128-bit data\n    }\n}","preventionTips":["Only convert RFC/Microsoft-conformant values into Guid","Validate variant bits once at your ingestion boundary","Keep opaque 128-bit identifiers as Hexadecimal, not Guid"],"tags":["php","ramsey-uuid","guid","variant-bits","binary-data","schema-validation"],"backgroundTag":"uuid-variant-validation-failed","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}