ramsey/uuid · error · InvalidArgumentException

Fields used to create a UuidV3 must represent a version 3 (n

Error message

Fields used to create a UuidV3 must represent a version 3 (name-based, MD5-hashed) UUID

What it means

Ramsey\Uuid\Rfc4122\UuidV3 wraps a field set that must represent a version 3 (name-based, MD5-hashed) UUID. The constructor checks $fields->getVersion() against Uuid::UUID_TYPE_HASH_MD5 (3) and throws Ramsey\Uuid\Exception\InvalidArgumentException for any other version nibble. This keeps the class's name-based semantics honest: a UuidV3 instance guarantees it was derived from an MD5 hash of a namespace plus name. The factory/builder normally performs this construction for you.

Source

Thrown at src/Rfc4122/UuidV3.php:50

final class UuidV3 extends Uuid implements UuidInterface
{
    /**
     * Creates a version 3 (name-based, MD5-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_MD5) {
            throw new InvalidArgumentException(
                'Fields used to create a UuidV3 must represent a version 3 (name-based, MD5-hashed) UUID',
            );
        }

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

View on GitHub (pinned to da5b521600)

Solutions

  1. Create v3 UUIDs with Uuid::uuid3($namespace, $name) instead of constructing UuidV3 directly
  2. Use Uuid::fromString($uuidString) to wrap existing values — it returns the correct UuidV* class for the version nibble
  3. Before manual construction, assert $fields->getVersion() === Uuid::UUID_TYPE_HASH_MD5 and correct the version bits otherwise
  4. In custom builders, dispatch on $fields->getVersion() and use the base Ramsey\Uuid\Uuid for versions you do not map explicitly

Example fix

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

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

// or let the builder pick the class from the string
$uuid = Uuid::fromString('6fa459ea-ee8a-3ca4-894e-db77e160355e'); // instanceof UuidV3
Defensive patterns

Strategy: validation

Validate before calling

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

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

Type guard

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

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

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

Try / catch

use Ramsey\Uuid\Exception\InvalidArgumentException;

try {
    $uuid = new UuidV3($fields, $numberConverter, $codec, $timeConverter);
} catch (InvalidArgumentException $e) {
    $uuid = Uuid::fromString($fields->getBytes() !== '' ? bin2hex($fields->getBytes()) : '');
}

Prevention

When it happens

Trigger: Calling new UuidV3($fields, $numberConverter, $codec, $timeConverter) with fields whose version nibble is not 3 — commonly fields decoded from a version 5 (SHA1) UUID string, or bytes from Uuid::uuid5()/uuid4(). Also custom builders/codecs that always instantiate UuidV3 regardless of the decoded version.

Common situations: Hand-wrapping decoded fields in a version-specific class instead of using Uuid::fromString(); mixing up v3 (MD5) and v5 (SHA1) name-based UUIDs; hardcoded class references in a custom codec; fixtures built from a v4 random UUID.

Related errors

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