ramsey/uuid · error · InvalidArgumentException

Fields used to create a UuidV1 must represent a version 1 (t

Error message

Fields used to create a UuidV1 must represent a version 1 (time-based) UUID

What it means

Rfc4122\UuidV1's constructor verifies that the given fields report version 1 (UUID_TYPE_TIME) before delegating to the parent; fields carrying any other version throw InvalidArgumentException. This keeps the concrete classes internally consistent — a UuidV1 instance must actually be a Gregorian time-based UUID.

Source

Thrown at src/Rfc4122/UuidV1.php:51

    use TimeTrait;

    /**
     * Creates a version 1 (Gregorian 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_TIME) {
            throw new InvalidArgumentException(
                'Fields used to create a UuidV1 must represent a version 1 (time-based) UUID',
            );
        }

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

View on GitHub (pinned to da5b521600)

Solutions

1. Use factories instead: Uuid::uuid1(), or Uuid::fromString() on a known-v1 string, then assert instanceof UuidV1
2. If constructing manually, feed fields from a genuine v1 UUID (e.g. Uuid::uuid1()->getFields())
3. Check $fields->getVersion() === Uuid::UUID_TYPE_TIME before invoking the constructor

Example fix

// before
$v1 = new \Ramsey\Uuid\Rfc4122\UuidV1($fields, $nc, $codec, $tc); // $fields is v4

// after
if ($fields->getVersion() !== \Ramsey\Uuid\Uuid::UUID_TYPE_TIME) {
    throw new InvalidArgumentException('fields must be version 1');
}
$v1 = new \Ramsey\Uuid\Rfc4122\UuidV1($fields, $nc, $codec, $tc);
// or simply: $v1 = \Ramsey\Uuid\Uuid::uuid1();

use Ramsey\Uuid\Uuid;
if ($fields->getVersion() !== Uuid::UUID_TYPE_TIME) {
    throw new InvalidArgumentException('UuidV1 requires version 1 fields');
}
$v1 = new \Ramsey\Uuid\Rfc4122\UuidV1($fields, $numberConverter, $codec, $timeConverter);

function isVersion1Fields(\Ramsey\Uuid\Rfc4122\FieldsInterface $fields): bool
{
    return $fields->getVersion() === \Ramsey\Uuid\Uuid::UUID_TYPE_TIME;
}

try {
    $v1 = new \Ramsey\Uuid\Rfc4122\UuidV1($fields, $nc, $codec, $tc);
} catch (\Ramsey\Uuid\Exception\InvalidArgumentException $e) {
    // fields/version mismatch; regenerate a true v1 instead
    $v1 = \Ramsey\Uuid\Uuid::uuid1();
}

When it happens

Trigger: Directly calling new UuidV1($fields, $numberConverter, $codec, $timeConverter) with fields whose version nibble is not 1 — e.g. reusing fields decoded from a v4 string, or a DI container/test fixture autowiring the constructor. The factories (Uuid::uuid1(), Uuid::fromString() of a v1 value) never mismatch fields, so this is a manual-construction error.

Common situations: Custom codecs/builders that re-wrap fields into a specific version class; code copying the constructor pattern from docs with wrong fields; tests constructing version objects by hand; refactors that mix field sets across versions.

Related errors

• Static node value cannot be greater than 12 hexadecimal char
• The byte string must be 16 bytes long; received {} bytes
• Expected version 1 (time-based) UUID
• Not a time-based UUID
• The generated time of '%s' is larger than expected

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