ramsey/uuid · error · NameException

Unable to hash namespace and name with algorithm

Error message

Unable to hash namespace and name with algorithm '%s'

What it means

PeclUuidNameGenerator is the name-based-UUID generator that ramsey/uuid wires in automatically when the PECL uuid extension (ext-uuid) is loaded. Its generate() only recognizes the case-sensitive strings 'md5' and 'sha1', mapping them to uuid_generate_md5() and uuid_generate_sha1(); any other hash algorithm falls through the match to the default arm, which throws NameException.

Solutions

Pass only 'md5' (version 3) or 'sha1' (version 5) as the hash algorithm
Whitelist before calling: in_array($algo, ['md5', 'sha1'], true), else fail with your own error before reaching the generator
If you genuinely need other hash algorithms, use the pure-PHP DefaultNameGenerator (built on hash()) instead of the PECL-based generator

Example fix

// before
$uuid = $featureSet->getNameGenerator()->generate($ns, $name, 'sha256');

// after
$algo = strtolower($algo);
if (!in_array($algo, ['md5', 'sha1'], true)) {
    throw new InvalidArgumentException('Only md5 and sha1 are supported');
}
$uuid = $featureSet->getNameGenerator()->generate($ns, $name, $algo);

Defensive patterns

Strategy: validation

Validate before calling

$allowed = ['md5', 'sha1'];
if (!in_array($hashAlgorithm, $allowed, true)) {
    throw new InvalidArgumentException(
        'Unsupported hash algorithm: ' . $hashAlgorithm . '; use ' . implode(' or ', $allowed)
    );
}
$uuidString = $generator->generate($ns, $name, $hashAlgorithm);

Type guard

/** @param string $algo */
function isSupportedNameHashAlgorithm(string $algo): bool
{
    return in_array($algo, ['md5', 'sha1'], true);
}

Try / catch

try {
    $name = $generator->generate($ns, $name, $algo);
} catch (\Ramsey\Uuid\Exception\NameException $e) {
    // algorithm not supported by this generator; fall back to factory uuid3/uuid5
}

Prevention

Never pass user input directly as the hash algorithm; map it to a fixed constant
Canonicalize to lowercase and whitelist before any generator call
Remember uuid3=md5 and uuid5=sha1 are the only RFC 9562 name-based versions

When it happens

Trigger: Calling $generator->generate($ns, $name, $hashAlgorithm) directly (or via a custom FeatureSet/UuidFactory that uses PeclUuidNameGenerator) with anything except exactly 'md5' or 'sha1' — e.g. 'sha256', 'MD5', or an algorithm name taken from user input/config. Uuid::uuid3()/uuid5() always pass 'md5'/'sha1', so the standard factory path never triggers this.

Common situations: Switching to ext-uuid for performance and reusing an algorithm constant from elsewhere; case or typo mismatches in the algorithm string; attempting SHA-256 name-based UUIDs, which neither RFC 9562 nor this generator support.

Related errors

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

Appendix: source

Thrown at src/Generator/PeclUuidNameGenerator.php:40

use function uuid_generate_sha1;
use function uuid_parse;

/**
 * PeclUuidNameGenerator generates strings of binary data from a namespace and a name, using ext-uuid
 *
 * @link https://pecl.php.net/package/uuid ext-uuid
 */
class PeclUuidNameGenerator implements NameGeneratorInterface
{
    /**
     * @pure
     */
    public function generate(UuidInterface $ns, string $name, string $hashAlgorithm): string
    {
        $uuid = match ($hashAlgorithm) {
            'md5' => uuid_generate_md5($ns->toString(), $name), /** @phpstan-ignore possiblyImpure.functionCall */
            'sha1' => uuid_generate_sha1($ns->toString(), $name), /** @phpstan-ignore possiblyImpure.functionCall */
            default => throw new NameException(
                sprintf('Unable to hash namespace and name with algorithm \'%s\'', $hashAlgorithm),
            ),
        };

        /** @phpstan-ignore possiblyImpure.functionCall */
        return (string) uuid_parse($uuid);
    }
}

View on GitHub (pinned to da5b521600)