{"record":{"id":"6bd1497f3fba4c45","repo":"ramsey/uuid","slug":"the-byte-string-received-does-not-conform-to-the-r-6bd149","errorCode":null,"errorMessage":"The byte string received does not conform to the RFC 9562 (formerly RFC 4122) variant","messagePattern":"The byte string received does not conform to the RFC 9562 \\(formerly RFC 4122\\) variant","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Rfc4122/Fields.php","lineNumber":64,"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 an RFC 9562 (formerly RFC 4122) UUID\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) variant',\n            );\n        }\n\n        if (!$this->isCorrectVersion()) {\n            throw new InvalidArgumentException(\n                'The byte string received does not contain a valid RFC 9562 (formerly RFC 4122) version',\n            );\n        }\n    }\n\n    /**\n     * @pure\n     */\n    public function getBytes(): string\n    {\n        return $this->bytes;\n    }","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Rfc4122/Fields.php#L46-L82","documentation":"Rfc4122\\Fields validates the variant bits for standard UUIDs: the top bits of clock_seq_hi_and_reserved (first hex character of the UUID's 4th group) must be 10xx, i.e. 8, 9, a, or b. Nil and max UUIDs bypass the check. Bytes whose variant nibble is 0-7 (NCS/reserved), c-d (Microsoft), or e-f (future reserved) are rejected with InvalidArgumentException. Because UuidBuilder wraps failures, this message usually arrives as the message of an UnableToBuildUuidException.","triggerScenarios":"Uuid::fromString('12345678-1234-4fff-ffff-123456789abc') — the 4th group starts with 'f', so the variant bits are 1111 and parsing throws this error (wrapped by UnableToBuildUuidException). Also direct Rfc4122\\Fields construction or custom codecs with non-RFC bytes. Uuid::isValid() passes these strings since it only checks hex format.","commonSituations":"Parsing log-stripped or hand-typed UUIDs with a typo in the 4th group; accepting IDs from other systems that emit non-RFC variant bits; test fixtures with placeholder hex like all-f; bit-mangling transformations that touch the clock_seq bytes.","solutions":["Validate before parsing: first hex char of the 4th group must be one of 8,9,a,b","Reject at the boundary by catching UnableToBuildUuidException when parsing untrusted UUID strings","Treat Microsoft-variant GUIDs (c/d) as Guid via Guid::fromString(), not Uuid::fromString()"],"exampleFix":"// before\n$uuid = \\Ramsey\\Uuid\\Uuid::fromString($candidate); // variant nibble invalid\n\n// after\nfunction isRfc4122Variant(string $s): bool\n{\n    $c = strtolower(preg_replace('/[^0-9a-f]/i', '', $s)[16] ?? '0');\n    return in_array($c, ['8', '9', 'a', 'b'], true);\n}\n$uuid = isRfc4122Variant($candidate)\n    ? \\Ramsey\\Uuid\\Uuid::fromString($candidate)\n    : throw new InvalidArgumentException('Not an RFC 9562 variant UUID');","handlingStrategy":"validation","validationCode":"$hex = strtolower(preg_replace('/[^0-9a-f]/i', '', $candidate));\n$variantNibble = $hex[16] ?? '';\nif (!in_array($variantNibble, ['8', '9', 'a', 'b'], true)) {\n    throw new InvalidArgumentException('Not an RFC 9562 variant UUID');\n}\n$uuid = \\Ramsey\\Uuid\\Uuid::fromString($candidate);","typeGuard":"function isRfc4122VariantString(string $uuid): bool\n{\n    $hex = strtolower(preg_replace('/^urn:uuid:|[^0-9a-f]/i', '', $uuid));\n    return strlen($hex) === 32\n        && in_array($hex[16], ['8', '9', 'a', 'b'], true);\n}","tryCatchPattern":"try {\n    $uuid = \\Ramsey\\Uuid\\Uuid::fromString($input);\n} catch (\\Ramsey\\Uuid\\Exception\\UnableToBuildUuidException $e) {\n    if (str_contains($e->getMessage(), 'variant')) {\n        // variant bits wrong: 4th group must start with 8/9/a/b\n    }\n}","preventionTips":["Uuid::isValid() checks format only; also check variant and version nibbles for untrusted input","Normalize Microsoft-variant GUIDs through Guid::fromString()","Reject all-f placeholder fixtures in tests in favor of the real Max UUID string"],"tags":["php","ramsey-uuid","variant-bits","rfc-9562","parsing","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"}