{"record":{"id":"bdbc19bac12e1ac0","repo":"ramsey/uuid","slug":"fields-used-to-create-a-uuidv5-must-represent-a-ve","errorCode":null,"errorMessage":"Fields used to create a UuidV5 must represent a version 5 (named-based, SHA1-hashed) UUID","messagePattern":"Fields used to create a UuidV5 must represent a version 5 \\(named-based, SHA1-hashed\\) UUID","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Rfc4122/UuidV5.php","lineNumber":50,"sourceCode":"final class UuidV5 extends Uuid implements UuidInterface\n{\n    /**\n     * Creates a version 5 (name-based, SHA1-hashed) UUID\n     *\n     * @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID\n     * @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers\n     * @param CodecInterface $codec The codec to use when encoding or decoding UUID strings\n     * @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a\n     *     UUID to unix timestamps\n     */\n    public function __construct(\n        Rfc4122FieldsInterface $fields,\n        NumberConverterInterface $numberConverter,\n        CodecInterface $codec,\n        TimeConverterInterface $timeConverter,\n    ) {\n        if ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_SHA1) {\n            throw new InvalidArgumentException(\n                'Fields used to create a UuidV5 must represent a version 5 (named-based, SHA1-hashed) UUID',\n            );\n        }\n\n        parent::__construct($fields, $numberConverter, $codec, $timeConverter);\n    }\n}\n","sourceCodeStart":32,"sourceCodeEnd":58,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Rfc4122/UuidV5.php#L32-L58","documentation":"Ramsey\\Uuid\\Rfc4122\\UuidV5 wraps a field set that must represent a version 5 (name-based, SHA1-hashed) UUID. The constructor checks $fields->getVersion() against Uuid::UUID_TYPE_HASH_SHA1 (5) and throws Ramsey\\Uuid\\Exception\\InvalidArgumentException for any other nibble. The check preserves the class invariant that a UuidV5 was derived from a SHA1 hash of a namespace plus name. The factory and builder normally instantiate this class only for genuinely version-5 bytes.","triggerScenarios":"Calling new UuidV5($fields, $numberConverter, $codec, $timeConverter) with fields whose version nibble is not 5 — typically fields decoded from a version 3 (MD5) UUID, or bytes from Uuid::uuid3()/uuid4(). Also custom builder code that instantiates UuidV5 unconditionally.","commonSituations":"Swapping an MD5-based scheme to SHA1 (or vice versa) while wrapper code still references the wrong class; decoding external UUIDs and assuming they are v5; custom codecs on GUID systems remapping fields with a stale version nibble.","solutions":["Generate v5 UUIDs with Uuid::uuid5($namespace, $name) instead of constructing UuidV5 directly","Wrap existing values with Uuid::fromString($string) / Uuid::fromBytes($bytes), which choose the matching class","Assert $fields->getVersion() === Uuid::UUID_TYPE_HASH_SHA1 before manual construction and repair the version bits otherwise","In custom builders, switch on getVersion() and use the base Ramsey\\Uuid\\Uuid class for non-v5 versions"],"exampleFix":"// before: $fields decoded from a version 3 (MD5) UUID string\n$uuid = new UuidV5($fields, $numberConverter, $codec, $timeConverter);\n// InvalidArgumentException: Fields used to create a UuidV5 must represent a version 5 (named-based, SHA1-hashed) UUID\n\n// after: generate with the factory\n$uuid = Uuid::uuid5($namespace, 'example.com');\n\n// or let the builder resolve the class\n$uuid = Uuid::fromString('886313e1-3b8a-5372-9b90-0c9aee199e5d'); // instanceof UuidV5","handlingStrategy":"validation","validationCode":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Uuid;\n\n// Run before constructing UuidV5\nif ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_SHA1) {\n    throw new \\InvalidArgumentException(\n        'Cannot build UuidV5 from version ' . $fields->getVersion() . ' fields'\n    );\n}","typeGuard":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Rfc4122\\UuidV5;\nuse Ramsey\\Uuid\\Uuid;\n\nfunction isVersion5Fields(FieldsInterface $fields): bool\n{\n    return $fields->getVersion() === Uuid::UUID_TYPE_HASH_SHA1;\n}\n\n$uuid = Uuid::fromString($value);\nif ($uuid instanceof UuidV5) {\n    // safe to treat as SHA1 name-based\n}","tryCatchPattern":"use Ramsey\\Uuid\\Exception\\InvalidArgumentException;\n\ntry {\n    $uuid = new UuidV5($fields, $numberConverter, $codec, $timeConverter);\n} catch (InvalidArgumentException $e) {\n    $uuid = new Ramsey\\Uuid\\Uuid($fields, $numberConverter, $codec, $timeConverter);\n}","preventionTips":["Generate with Uuid::uuid5($namespace, $name); wrap with Uuid::fromString()","When migrating MD5 (v3) schemes to SHA1 (v5), update every hardcoded class reference","Assert the version nibble before direct construction","Map versions to classes dynamically in custom builders"],"tags":["php","ramsey-uuid","uuid","validation","constructor","version-mismatch","sha1"],"backgroundTag":"uuid-version-mismatch","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}