{"record":{"id":"ff3f6655537777c4","repo":"ramsey/uuid","slug":"clock-sequence-out-of-bounds-it-must-be-a-value-b","errorCode":null,"errorMessage":"Clock sequence out of bounds; it must be a value between 0 and 63","messagePattern":"Clock sequence out of bounds; it must be a value between 0 and 63","errorType":"exception","errorClass":"DceSecurityException","httpStatus":null,"severity":"error","filePath":"src/Generator/DceSecurityGenerator.php","lineNumber":79,"sourceCode":"\n    public function generate(\n        int $localDomain,\n        ?IntegerObject $localIdentifier = null,\n        ?Hexadecimal $node = null,\n        ?int $clockSeq = null,\n    ): string {\n        if (!in_array($localDomain, self::DOMAINS)) {\n            throw new DceSecurityException('Local domain must be a valid DCE Security domain');\n        }\n\n        if ($localIdentifier && $localIdentifier->isNegative()) {\n            throw new DceSecurityException(\n                'Local identifier out of bounds; it must be a value between 0 and 4294967295',\n            );\n        }\n\n        if ($clockSeq > self::CLOCK_SEQ_HIGH || $clockSeq < self::CLOCK_SEQ_LOW) {\n            throw new DceSecurityException('Clock sequence out of bounds; it must be a value between 0 and 63');\n        }\n\n        switch ($localDomain) {\n            case Uuid::DCE_DOMAIN_ORG:\n                if ($localIdentifier === null) {\n                    throw new DceSecurityException('A local identifier must be provided for the org domain');\n                }\n\n                break;\n            case Uuid::DCE_DOMAIN_PERSON:\n                if ($localIdentifier === null) {\n                    $localIdentifier = $this->dceSecurityProvider->getUid();\n                }\n\n                break;\n            case Uuid::DCE_DOMAIN_GROUP:\n            default:\n                if ($localIdentifier === null) {","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Generator/DceSecurityGenerator.php#L61-L97","documentation":"In DCE Security (version 2) UUIDs the clock sequence field is only 6 bits, so DceSecurityGenerator enforces 0..63 (CLOCK_SEQ_LOW..CLOCK_SEQ_HIGH) and throws DceSecurityException outside that range. This is much narrower than the 14-bit clock sequence of ordinary v1 UUIDs (0..16383).","triggerScenarios":"Uuid::uuid2(..., $clockSeq) with values like 1000; reusing a v1 clock sequence constant; passing an unsigned 14-bit value read from another UUID.","commonSituations":"Porting v1 generation parameters to uuid2(); hardcoded clock sequence from legacy config written for the v1 field width; generated/fuzzed test values outside 0..63.","solutions":["Pass null to let the generator pick a value, or constrain to 0..63.","Mask when porting v1-style values: $clockSeq & 0x3f.","Validate configuration constants against the 0..63 range at startup."],"exampleFix":"// before\n$uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON, null, null, 4096); // > 63\n\n// after\n$uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON, null, null, 4096 & 0x3f);","handlingStrategy":"validation","validationCode":"if ($clockSeq !== null && ($clockSeq < 0 || $clockSeq > 63)) {\n    $clockSeq = $clockSeq & 0x3f; // clamp to the 6-bit v2 field\n}\n$uuid = Uuid::uuid2($domain, $identifier, $node, $clockSeq);","typeGuard":"function isValidDceClockSeq(?int $clockSeq): bool\n{\n    return $clockSeq === null || ($clockSeq >= 0 && $clockSeq <= 63);\n}","tryCatchPattern":"try {\n    $uuid = Uuid::uuid2($domain, $id, null, $clockSeq);\n} catch (\\Ramsey\\Uuid\\Exception\\DceSecurityException $e) {\n    $uuid = Uuid::uuid2($domain, $id); // retry with a generated clock sequence\n}","preventionTips":["Remember v2 clock sequence is 6 bits (0..63), unlike v1's 14 bits.","Pass null and let the generator choose when you have no strong requirement.","Validate legacy clock-sequence constants from v1 configs before reuse.","Mask inbound values with & 0x3f at the configuration boundary."],"tags":["php","ramsey-uuid","dce-security","uuid-v2","clock-sequence","out-of-range"],"backgroundTag":"clock-sequence-out-of-range","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}