ramsey/uuid · error · NameException

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

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.

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)

Solutions

1. Pass only 'md5' (version 3) or 'sha1' (version 5) as the hash algorithm
2. Whitelist before calling: in_array($algo, ['md5', 'sha1'], true), else fail with your own error before reaching the generator
3. 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);

$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);

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

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
}

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

• Unable to hash namespace and name with algorithm '%s'
• The byte string must be 16 bytes long; received {bytes} byte
• Fields used to create a UuidV6 must represent a version 6 (r
• Static node value cannot be greater than 12 hexadecimal char
• The byte string must be 16 bytes long; received {} bytes

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