{"record":{"id":"36b4b5d784c332cf","repo":"ramsey/uuid","slug":"fields-used-to-create-a-uuidv2-must-represent-a-ve","errorCode":null,"errorMessage":"Fields used to create a UuidV2 must represent a version 2 (DCE Security) UUID","messagePattern":"Fields used to create a UuidV2 must represent a version 2 \\(DCE Security\\) UUID","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Rfc4122/UuidV2.php","lineNumber":70,"sourceCode":"    use TimeTrait;\n\n    /**\n     * Creates a version 2 (DCE Security) 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_DCE_SECURITY) {\n            throw new InvalidArgumentException(\n                'Fields used to create a UuidV2 must represent a version 2 (DCE Security) UUID'\n            );\n        }\n\n        parent::__construct($fields, $numberConverter, $codec, $timeConverter);\n    }\n\n    /**\n     * Returns the local domain used to create this version 2 UUID\n     */\n    public function getLocalDomain(): int\n    {\n        /** @var Rfc4122FieldsInterface $fields */\n        $fields = $this->getFields();\n\n        return (int) hexdec($fields->getClockSeqLow()->toString());\n    }\n","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Rfc4122/UuidV2.php#L52-L88","documentation":"Ramsey\\Uuid\\Rfc4122\\UuidV2 wraps an existing field set that must represent a version 2 (DCE Security) UUID. Its constructor verifies the version nibble via $fields->getVersion() against Uuid::UUID_TYPE_DCE_SECURITY (2) and throws Ramsey\\Uuid\\Exception\\InvalidArgumentException on any other value. The guard exists because UuidV2 exposes version-specific accessors (getLocalDomain(), getLocalIdentifier(), getLocalNode()) that would return meaningless data for mismatched fields. In normal usage you never call this constructor directly; the factory and builder call it only for bytes whose version nibble is 2.","triggerScenarios":"Calling new UuidV2($fields, $numberConverter, $codec, $timeConverter) with a Ramsey\\Uuid\\Rfc4122\\Fields instance whose version nibble is not 2 — for example fields decoded from a v4 string via a codec, or bytes produced by Uuid::uuid4()/uuid1(). Also a custom Builder or Codec that unconditionally instantiates UuidV2 for every UUID it decodes.","commonSituations":"Copying low-level constructor examples instead of using the factory; custom codecs/builders (e.g. GUID byte-order handling on little-endian systems) that map every decoded UUID to one version class; test fixtures that hand-assemble field sets with the wrong version bits; mutating UUID bytes without fixing the version nibble.","solutions":["Generate version 2 UUIDs through the factory: Uuid::uuid2($localDomain, $identifier, $node, $clockSeq) instead of new UuidV2(...)","When wrapping existing values, use Uuid::fromString($string) or Uuid::fromBytes($bytes) — the builder selects the version-matching class automatically","If you must construct manually, first verify $fields->getVersion() === Uuid::UUID_TYPE_DCE_SECURITY and fix the version bits in the input bytes when it differs","In a custom builder, switch on $fields->getVersion() and instantiate UuidV2 only for version 2; fall back to the base Ramsey\\Uuid\\Uuid class for other versions"],"exampleFix":"// before: fields carry version 4 bits, but UuidV2 is constructed directly\n$uuid = new UuidV2($fields, $numberConverter, $codec, $timeConverter);\n// InvalidArgumentException: Fields used to create a UuidV2 must represent a version 2 (DCE Security) UUID\n\n// after: generate v2 UUIDs through the factory\n$uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON, 1001);\n\n// or wrap existing bytes with the version-agnostic builder\n$uuid = Uuid::fromBytes($bytes); // returns UuidV2 only when the version nibble is 2","handlingStrategy":"validation","validationCode":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Uuid;\n\n// Run before constructing UuidV2\nif ($fields->getVersion() !== Uuid::UUID_TYPE_DCE_SECURITY) {\n    // do not construct UuidV2 with these fields\n    throw new \\InvalidArgumentException(\n        'Cannot build UuidV2 from version ' . $fields->getVersion() . ' fields'\n    );\n}","typeGuard":"use Ramsey\\Uuid\\Rfc4122\\FieldsInterface;\nuse Ramsey\\Uuid\\Rfc4122\\UuidV2;\nuse Ramsey\\Uuid\\Uuid;\n\nfunction isVersion2Fields(FieldsInterface $fields): bool\n{\n    return $fields->getVersion() === Uuid::UUID_TYPE_DCE_SECURITY;\n}\n\n// after decoding, narrow instead of assuming\n$uuid = Uuid::fromString($value);\nif ($uuid instanceof UuidV2) {\n    $domain = $uuid->getLocalDomain();\n}","tryCatchPattern":"use Ramsey\\Uuid\\Exception\\InvalidArgumentException;\n\ntry {\n    $uuid = new UuidV2($fields, $numberConverter, $codec, $timeConverter);\n} catch (InvalidArgumentException $e) {\n    // Log the actual version and fall back to the version-agnostic class\n    $uuid = new Ramsey\\Uuid\\Uuid($fields, $numberConverter, $codec, $timeConverter);\n}","preventionTips":["Prefer Uuid::uuid2() for generation and Uuid::fromString()/fromBytes() for wrapping — they never throw this error","Check $fields->getVersion() before instantiating any version-specific UuidV* class","Never assume a decoded UUID's version; switch on getVersion()","In custom builders, map each version to its class and default to the base Uuid"],"tags":["php","ramsey-uuid","uuid","validation","constructor","version-mismatch"],"backgroundTag":"uuid-version-mismatch","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}