ramsey/uuid · error · InvalidArgumentException

Fields used to create a UuidV5 must represent a version 5 (n

Error message

Fields used to create a UuidV5 must represent a version 5 (named-based, SHA1-hashed) UUID

What it means

Ramsey\Uuid\Rfc4122\UuidV5 wraps a field set that must represent a version 5 (name-based, SHA1-hashed) UUID. The constructor checks $fields->getVersion() against Uuid::UUID_TYPE_HASH_SHA1 (5) and throws Ramsey\Uuid\Exception\InvalidArgumentException for any other nibble. The check preserves the class invariant that a UuidV5 was derived from a SHA1 hash of a namespace plus name. The factory and builder normally instantiate this class only for genuinely version-5 bytes.

Source

Thrown at src/Rfc4122/UuidV5.php:50

final class UuidV5 extends Uuid implements UuidInterface
{
    /**
     * Creates a version 5 (name-based, SHA1-hashed) UUID
     *
     * @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
     * @param NumberConverterInterface $numberConverter The number converter to use for converting hex values to/from integers
     * @param CodecInterface $codec The codec to use when encoding or decoding UUID strings
     * @param TimeConverterInterface $timeConverter The time converter to use for converting timestamps extracted from a
     *     UUID to unix timestamps
     */
    public function __construct(
        Rfc4122FieldsInterface $fields,
        NumberConverterInterface $numberConverter,
        CodecInterface $codec,
        TimeConverterInterface $timeConverter,
    ) {
        if ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_SHA1) {
            throw new InvalidArgumentException(
                'Fields used to create a UuidV5 must represent a version 5 (named-based, SHA1-hashed) UUID',
            );
        }

        parent::__construct($fields, $numberConverter, $codec, $timeConverter);
    }
}

View on GitHub (pinned to da5b521600)

Solutions

1. Generate v5 UUIDs with Uuid::uuid5($namespace, $name) instead of constructing UuidV5 directly
2. Wrap existing values with Uuid::fromString($string) / Uuid::fromBytes($bytes), which choose the matching class
3. Assert $fields->getVersion() === Uuid::UUID_TYPE_HASH_SHA1 before manual construction and repair the version bits otherwise
4. In custom builders, switch on getVersion() and use the base Ramsey\Uuid\Uuid class for non-v5 versions

Example fix

// before: $fields decoded from a version 3 (MD5) UUID string
$uuid = new UuidV5($fields, $numberConverter, $codec, $timeConverter);
// InvalidArgumentException: Fields used to create a UuidV5 must represent a version 5 (named-based, SHA1-hashed) UUID

// after: generate with the factory
$uuid = Uuid::uuid5($namespace, 'example.com');

// or let the builder resolve the class
$uuid = Uuid::fromString('886313e1-3b8a-5372-9b90-0c9aee199e5d'); // instanceof UuidV5

use Ramsey\Uuid\Rfc4122\FieldsInterface;
use Ramsey\Uuid\Uuid;

// Run before constructing UuidV5
if ($fields->getVersion() !== Uuid::UUID_TYPE_HASH_SHA1) {
    throw new \InvalidArgumentException(
        'Cannot build UuidV5 from version ' . $fields->getVersion() . ' fields'
    );
}

use Ramsey\Uuid\Rfc4122\FieldsInterface;
use Ramsey\Uuid\Rfc4122\UuidV5;
use Ramsey\Uuid\Uuid;

function isVersion5Fields(FieldsInterface $fields): bool
{
    return $fields->getVersion() === Uuid::UUID_TYPE_HASH_SHA1;
}

$uuid = Uuid::fromString($value);
if ($uuid instanceof UuidV5) {
    // safe to treat as SHA1 name-based
}

use Ramsey\Uuid\Exception\InvalidArgumentException;

try {
    $uuid = new UuidV5($fields, $numberConverter, $codec, $timeConverter);
} catch (InvalidArgumentException $e) {
    $uuid = new Ramsey\Uuid\Uuid($fields, $numberConverter, $codec, $timeConverter);
}

When it happens

Trigger: Calling new UuidV5($fields, $numberConverter, $codec, $timeConverter) with fields whose version nibble is not 5 — typically fields decoded from a version 3 (MD5) UUID, or bytes from Uuid::uuid3()/uuid4(). Also custom builder code that instantiates UuidV5 unconditionally.

Common situations: Swapping an MD5-based scheme to SHA1 (or vice versa) while wrapper code still references the wrong class; decoding external UUIDs and assuming they are v5; custom codecs on GUID systems remapping fields with a stale version nibble.

Related errors

• Fields used to create a UuidV2 must represent a version 2 (D
• Fields used to create a UuidV3 must represent a version 3 (n
• Fields used to create a UuidV4 must represent a version 4 (r
• Fields used to create a UuidV7 must represent a version 7 (U
• Fields used to create a UuidV8 must represent a version 8 (c

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