ramsey/uuid · error · DceSecurityException

A local identifier must be provided for the org domain

Error message

A local identifier must be provided for the org domain

What it means

DceSecurityGenerator can auto-derive the local identifier only for the person domain (via the DCE security provider's getUid()) and the group domain (getGid()); there is no system source for the org domain, so generate() throws DceSecurityException when $localIdentifier is null for DCE_DOMAIN_ORG.

Source

Thrown at src/Generator/DceSecurityGenerator.php:85

    ): string {
        if (!in_array($localDomain, self::DOMAINS)) {
            throw new DceSecurityException('Local domain must be a valid DCE Security domain');
        }

        if ($localIdentifier && $localIdentifier->isNegative()) {
            throw new DceSecurityException(
                'Local identifier out of bounds; it must be a value between 0 and 4294967295',
            );
        }

        if ($clockSeq > self::CLOCK_SEQ_HIGH || $clockSeq < self::CLOCK_SEQ_LOW) {
            throw new DceSecurityException('Clock sequence out of bounds; it must be a value between 0 and 63');
        }

        switch ($localDomain) {
            case Uuid::DCE_DOMAIN_ORG:
                if ($localIdentifier === null) {
                    throw new DceSecurityException('A local identifier must be provided for the org domain');
                }

                break;
            case Uuid::DCE_DOMAIN_PERSON:
                if ($localIdentifier === null) {
                    $localIdentifier = $this->dceSecurityProvider->getUid();
                }

                break;
            case Uuid::DCE_DOMAIN_GROUP:
            default:
                if ($localIdentifier === null) {
                    $localIdentifier = $this->dceSecurityProvider->getGid();
                }

                break;
        }

View on GitHub (pinned to da5b521600)

Solutions

1. Pass an explicit identifier for the org domain: Uuid::uuid2(Uuid::DCE_DOMAIN_ORG, new Integer($orgId)).
2. If you do not have a real org identifier, use the person or group domain, which default to the provider's uid/gid.
3. Supply a custom DceSecurityProviderInterface only if you can derive org ids yourself - the built-in provider still cannot.

Example fix

// before
$uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_ORG); // DceSecurityException

// after
$uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_ORG, new Integer(1337));

$identifier = $localDomain === Uuid::DCE_DOMAIN_ORG
    ? new Integer($orgId ?? throw new InvalidArgumentException('org domain requires an explicit local identifier'))
    : ($localId !== null ? new Integer($localId) : null);

$uuid = Uuid::uuid2($localDomain, $identifier);

function hasRequiredDceIdentifier(int $localDomain, ?\Ramsey\Uuid\Type\Integer $identifier): bool
{
    return $identifier !== null || $localDomain !== Uuid::DCE_DOMAIN_ORG;
}

try {
    $uuid = Uuid::uuid2(Uuid::DCE_DOMAIN_ORG);
} catch (\Ramsey\Uuid\Exception\DceSecurityException $e) {
    // no system source for org ids - require one from the caller
    throw new InvalidConfigurationException('org domain needs an explicit identifier', $e);
}

When it happens

Trigger: Uuid::uuid2(Uuid::DCE_DOMAIN_ORG) with no second argument; org-domain generation where the caller assumed uid/gid-style defaults apply.

Common situations: Switching a codebase from person to org domain UUIDs without adding an identifier; wrappers that always omit the identifier; running in an environment (container) where devs assumed everything auto-derives.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Local domain must be a valid DCE Security domain
• Local identifier out of bounds; it must be a value between 0
• Clock sequence out of bounds; it must be a value between 0 a
• Unable to get a user identifier using the system DCE Securit
• Unable to get a group identifier using the system DCE Securi

AI-assisted analysis of ramsey/uuid@da5b521600 (2026-08-21). Data as JSON: /api/errors/af0bfab0b9a729a4. Report an issue: GitHub.