{"record":{"id":"2c966fdac91ef35c","repo":"ramsey/uuid","slug":"local-identifier-out-of-bounds-it-must-be-a-value","errorCode":null,"errorMessage":"Local identifier out of bounds; it must be a value between 0 and 4294967295","messagePattern":"Local identifier out of bounds; it must be a value between 0 and 4294967295","errorType":"exception","errorClass":"DceSecurityException","httpStatus":null,"severity":"error","filePath":"src/Generator/DceSecurityGenerator.php","lineNumber":73,"sourceCode":"    public function __construct(\n        private NumberConverterInterface $numberConverter,\n        private TimeGeneratorInterface $timeGenerator,\n        private DceSecurityProviderInterface $dceSecurityProvider,\n    ) {\n    }\n\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();","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Generator/DceSecurityGenerator.php#L55-L91","documentation":"When generating a DCE Security (version 2) UUID, a negative IntegerObject local identifier is rejected with DceSecurityException because the field is an unsigned 32-bit value (0..4294967295). The check runs before any identifier auto-derivation.","triggerScenarios":"Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON, new Integer(-1)); passing a sentinel negative value; a system call that returns -1 on failure and is wrapped unchecked into Integer.","commonSituations":"Using -1 as an 'unknown id' sentinel; error returns from posix/external systems fed straight into the generator; IDs arriving as signed values from another platform.","solutions":["Pass a non-negative IntegerObject (or null to auto-derive uid/gid for person/group domains).","Handle -1 sentinels at the source: treat them as 'unknown' and pass null instead.","Clamp/mask upstream values to the 0..4294967295 range before constructing the Integer."],"exampleFix":"// before\n$uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON, new Integer($uid)); // $uid === -1\n\n// after\n$identifier = $uid >= 0 ? new Integer($uid) : null;\n$uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_PERSON, $identifier);","handlingStrategy":"validation","validationCode":"if ($identifier !== null && ($identifier->isNegative() || $identifier->compareTo(new Integer(4294967295)) > 0)) {\n    throw new InvalidArgumentException('local identifier must be 0..4294967295');\n}\n$uuid = Uuid::uuid2($domain, $identifier);","typeGuard":"function isValidDceIdentifier(\\Ramsey\\Uuid\\Type\\Integer $id): bool\n{\n    return !$id->isNegative() && $id->compareTo(new \\Ramsey\\Uuid\\Type\\Integer(4294967295)) <= 0;\n}","tryCatchPattern":"try {\n    $uuid = Uuid::uuid2($domain, new Integer($uid));\n} catch (\\Ramsey\\Uuid\\Exception\\DceSecurityException $e) {\n    // treat as unknown identity\n    $uuid = Uuid::uuid2($domain);\n}","preventionTips":["Translate -1/never-set sentinels into null before building the Integer.","Check isNegative() on IntegerObject values coming from external systems.","Pass null for person/group to auto-derive uid/gid when the real id is unknown."],"tags":["php","ramsey-uuid","dce-security","uuid-v2","local-identifier","out-of-range"],"backgroundTag":"identifier-out-of-range","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}