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

DefaultNameGenerator::generate() calls PHP's hash($hashAlgorithm, $ns->getBytes() . $name, true); when the algorithm is unknown to the hash extension, PHP 8 raises ValueError, which this generator converts into a NameException naming the algorithm. It is the failure path for name-based (v3/v5-style) UUID generation with any algorithm not in hash_algos().

Source

Thrown at src/Generator/DefaultNameGenerator.php:36

use Ramsey\Uuid\UuidInterface;
use ValueError;

use function hash;

/**
 * DefaultNameGenerator generates strings of binary data based on a namespace, name, and hashing algorithm
 */
class DefaultNameGenerator implements NameGeneratorInterface
{
    /**
     * @pure
     */
    public function generate(UuidInterface $ns, string $name, string $hashAlgorithm): string
    {
        try {
            return hash($hashAlgorithm, $ns->getBytes() . $name, true);
        } catch (ValueError $e) {
            throw new NameException(
                message: sprintf('Unable to hash namespace and name with algorithm \'%s\'', $hashAlgorithm),
                previous: $e,
            );
        }
    }
}

View on GitHub (pinned to da5b521600)

Solutions

1. Whitelist before generating: in_array($algorithm, hash_algos(), true) and reject early.
2. For RFC 4122 v3/v5 UUIDs stick to 'md5' and 'sha1'.
3. Normalize names: strtolower + str_replace('-', '') + trim, then validate.

Example fix

// before
$bytes = $nameGenerator->generate($ns, $name, 'sha-256'); // NameException

// after
$algorithm = strtolower(str_replace('-', '', trim($configuredAlgorithm)));
if (!in_array($algorithm, hash_algos(), true)) {
    throw new InvalidArgumentException("unsupported hash algorithm: {$algorithm}");
}
$bytes = $nameGenerator->generate($ns, $name, $algorithm); // 'sha256'

$algorithm = strtolower(str_replace('-', '', trim($configuredAlgorithm)));
if (!in_array($algorithm, hash_algos(), true)) {
    throw new InvalidArgumentException(sprintf('unsupported hash algorithm: %s', $algorithm));
}
$bytes = $nameGenerator->generate($ns, $name, $algorithm);

function isSupportedHashAlgorithm(string $algorithm): bool
{
    return in_array(strtolower(trim($algorithm)), hash_algos(), true);
}

try {
    $bytes = $nameGenerator->generate($ns, $name, $algorithm);
} catch (\Ramsey\Uuid\Exception\NameException $e) {
    throw new InvalidConfigurationException("hash algorithm '{$algorithm}' unavailable on this PHP build", $e);
}

When it happens

Trigger: A factory or custom code path that hashes names with an invalid algorithm string: typos like 'sha-1'/'SHA-1 ' instead of 'sha1', algorithms missing on the deployed PHP build (e.g. 'xxh3', 'murmur3' on older PHP), or user/config-supplied algorithm names.

Common situations: Config-driven hash algorithms; code developed against a newer PHP/openssl build then deployed to an older runtime; hyphenated or uppercase algorithm names; whitespace from config files.

Related errors

• Unable to hash namespace and name with algorithm '%s'
• Could not find a suitable builder for the provided codec and
• Expected version 1 (time-based) UUID
• $bytes string should contain 16 characters.
• Attempting to decode a non-time-based UUID using OrderedTime

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