{"record":{"id":"338dfdf544b85280","repo":"ramsey/uuid","slug":"the-byte-string-received-does-not-contain-a-valid","errorCode":null,"errorMessage":"The byte string received does not contain a valid version","messagePattern":"The byte string received does not contain a valid version","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Guid/Fields.php","lineNumber":77,"sourceCode":"     * @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.\n        /** @var string[] $hex */\n        $hex = unpack(\n            'H*',\n            pack(\n                'v*',\n                hexdec(bin2hex(substr($this->bytes, 2, 2))),\n                hexdec(bin2hex(substr($this->bytes, 0, 2))),","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Guid/Fields.php#L59-L95","documentation":"Guid\\Fields uses VersionTrait::isCorrectVersion(): for non-nil, non-max UUIDs the version nibble (high nibble of byte 6 after the GUID byte swap, i.e. the first character of the string's 3rd group) must be one of 1-8. Versions 0 and 9-f are not defined by RFC 9562, so the constructor rejects them with InvalidArgumentException.","triggerScenarios":"Building a Guid from 16 bytes whose version nibble is 0 or 9-f, e.g. Guid::fromBytes(hex2bin('1234567812349abc8123456789abcdef')) — the '9' after the second group makes version 9 invalid. Also reached via custom builders feeding GuidBuilder::build().","commonSituations":"Parsing identifiers produced by non-RFC systems (ULIDs converted naively, content-hash derived 128-bit values, V1 UUIDs bit-shifted wrongly); corrupted or truncated binary payloads where the version nibble was damaged.","solutions":["Check the version nibble before constructing: hex digit at position 12 of the hex string must be 1-8 (nil/max all-zero or all-f are also allowed)","Only convert RFC-conformant 128-bit values to Guid; keep opaque values as hex/binary","Catch UnableToBuildUuidException at the parse boundary when input is untrusted"],"exampleFix":"// before\n$guid = \\Ramsey\\Uuid\\Guid\\Guid::fromBytes($bytes);\n\n// after\n$hex = bin2hex($bytes);\n$version = hexdec($hex[12]);\nif ($hex !== str_repeat('0', 32) && $hex !== str_repeat('f', 32) && ($version < 1 || $version > 8)) {\n    throw new InvalidArgumentException('Not an RFC 9562 version');\n}\n$guid = \\Ramsey\\Uuid\\Guid\\Guid::fromBytes($bytes);","handlingStrategy":"validation","validationCode":"$hex = bin2hex($bytes);\n$version = hexdec($hex[12]);\n$isSpecial = $hex === str_repeat('0', 32) || $hex === str_repeat('f', 32);\nif (!$isSpecial && ($version < 1 || $version > 8)) {\n    throw new InvalidArgumentException('Invalid UUID version nibble: ' . $hex[12]);\n}","typeGuard":"function hasGuidValidVersion(string $bytes): bool\n{\n    $hex = bin2hex($bytes);\n    if ($hex === str_repeat('0', 32) || $hex === str_repeat('f', 32)) {\n        return true;\n    }\n    $v = hexdec($hex[12]);\n    return $v >= 1 && $v <= 8;\n}","tryCatchPattern":"try {\n    $guid = \\Ramsey\\Uuid\\Guid\\Guid::fromBytes($bytes);\n} catch (\\Ramsey\\Uuid\\Exception\\UnableToBuildUuidException $e) {\n    // check message for 'valid version' to distinguish from variant/length failures\n}","preventionTips":["Validate the version nibble before converting external 128-bit values","Reject non-RFC identifiers at ingestion with a clear domain error","Log the offending hex so bad sources can be traced"],"tags":["php","ramsey-uuid","guid","version-nibble","schema-validation","rfc-9562"],"backgroundTag":"uuid-version-validation-failed","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}