ramsey/uuid · error · InvalidArgumentException

Fields used to create a UuidV7 must represent a version 7 (U

Error message

Fields used to create a UuidV7 must represent a version 7 (Unix Epoch time) UUID

What it means

Ramsey\Uuid\Rfc4122\UuidV7 wraps a field set that must represent a version 7 (Unix Epoch time-ordered) UUID. The constructor checks $fields->getVersion() against Uuid::UUID_TYPE_UNIX_TIME (7) and throws Ramsey\Uuid\Exception\InvalidArgumentException otherwise. The invariant matters because UuidV7 exposes time-based accessors (getDateTime()) that only make sense for the 48-bit Unix-timestamp layout. Version 7 support arrived in ramsey/uuid 4.7, so mixed-version environments are a common source of mismatched bytes.

Source

Thrown at src/Rfc4122/UuidV7.php:51

    use TimeTrait;

    /**
     * Creates a version 7 (Unix Epoch time) 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_UNIX_TIME) {
            throw new InvalidArgumentException(
                'Fields used to create a UuidV7 must represent a version 7 (Unix Epoch time) UUID',
            );
        }

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

View on GitHub (pinned to da5b521600)

Solutions

1. Generate v7 UUIDs with Uuid::uuid7($dateTime) instead of constructing UuidV7 manually
2. Wrap existing values with Uuid::fromString()/Uuid::fromBytes() so the builder resolves the class from the version nibble
3. Verify $fields->getVersion() === Uuid::UUID_TYPE_UNIX_TIME before constructing UuidV7 directly
4. In custom builders, branch on getVersion() (v1 -> UuidV1, v6 -> UuidV6, v7 -> UuidV7) instead of hardcoding one class

Example fix

// before: $fields carry version 6 bits but the code assumes v7
$uuid = new UuidV7($fields, $numberConverter, $codec, $timeConverter);
// InvalidArgumentException: Fields used to create a UuidV7 must represent a version 7 (Unix Epoch time) UUID

// after: generate a time-ordered v7
$uuid = Uuid::uuid7();

// or resolve the class from existing bytes
$uuid = Uuid::fromBytes($bytes);
if ($uuid instanceof \Ramsey\Uuid\Rfc4122\UuidV7) {
    $timestamp = $uuid->getDateTime();
}

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

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

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

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

$uuid = Uuid::fromString($value);
if ($uuid instanceof UuidV7) {
    $created = $uuid->getDateTime();
}

use Ramsey\Uuid\Exception\InvalidArgumentException;

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

When it happens

Trigger: Calling new UuidV7($fields, $numberConverter, $codec, $timeConverter) with fields whose version nibble is not 7 — e.g. fields from a v4 UUID produced by an older generator, or bytes from Uuid::uuid1(). Also custom builders that instantiate UuidV7 for every time-ordered UUID including v1/v6.

Common situations: Migrating from v4/v1 to v7 while application code still wraps all bytes in UuidV7; third-party systems emitting v6 (reordered time) UUIDs consumed as v7; fixture files with hardcoded v4 strings fed into v7 code paths.

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 UuidV5 must represent a version 5 (n
• 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/34fb0cb7d75e8d7e. Report an issue: GitHub.