ramsey/uuid · error · InvalidArgumentException

Length must be a positive integer greater than or equal to 6

Error message

Length must be a positive integer greater than or equal to 6

What it means

CombGenerator (deprecated in favor of UUIDv7) builds COMB identifiers by placing a 48-bit timestamp into a byte string of a requested length; generate() rejects lengths below TIMESTAMP_BYTES (6) with InvalidArgumentException because there would be no room for the timestamp.

Source

Thrown at src/Generator/CombGenerator.php:77

class CombGenerator implements RandomGeneratorInterface
{
    public const TIMESTAMP_BYTES = 6;

    public function __construct(
        private RandomGeneratorInterface $generator,
        private NumberConverterInterface $numberConverter
    ) {
    }

    /**
     * @throws InvalidArgumentException if $length is not a positive integer greater than or equal to CombGenerator::TIMESTAMP_BYTES
     *
     * @inheritDoc
     */
    public function generate(int $length): string
    {
        if ($length < self::TIMESTAMP_BYTES) {
            throw new InvalidArgumentException(
                'Length must be a positive integer greater than or equal to ' . self::TIMESTAMP_BYTES
            );
        }

        if ($length % 2 !== 0) {
            throw new InvalidArgumentException('Length must be an even number');
        }

        $hash = '';

        /** @phpstan-ignore greater.alwaysTrue (TIMESTAMP_BYTES constant could change in child classes) */
        if (self::TIMESTAMP_BYTES > 0 && $length > self::TIMESTAMP_BYTES) {
            $hash = $this->generator->generate($length - self::TIMESTAMP_BYTES);
        }

        $lsbTime = str_pad(
            $this->numberConverter->toHex($this->timestamp()),
            self::TIMESTAMP_BYTES * 2,

View on GitHub (pinned to da5b521600)

Solutions

1. Request a length of at least 6 bytes (and even).
2. Use RandomBytesGenerator when you need arbitrary-length random bytes without a timestamp.
3. Migrate time-ordered identifiers to Uuid::uuid7() - CombGenerator is deprecated.

Example fix

// before
$bytes = $combGenerator->generate(4); // InvalidArgumentException

// after
$bytes = $combGenerator->generate(16); // >= 6 and even
// or migrate: $uuid = Uuid::uuid7();

function assertCombLength(int $length): void
{
    if ($length < 6) {
        throw new InvalidArgumentException('COMB length must be >= 6 bytes');
    }
    if ($length % 2 !== 0) {
        throw new InvalidArgumentException('COMB length must be even');
    }
}

assertCombLength($length);
$bytes = $combGenerator->generate($length);

function isValidCombLength(int $length): bool
{
    return $length >= 6 && $length % 2 === 0;
}

When it happens

Trigger: $combGenerator->generate(4) (or any length under 6); adapting CombGenerator as a general-purpose random generator and requesting small sizes.

Common situations: Custom token/ID code reusing the CombGenerator example with arbitrary lengths; assuming it behaves like RandomBytesGenerator for any size; legacy COMB code touched during a UUIDv7 migration.

Related errors

• Length must be an even number
• Not a time-based UUID
• Fields used to create a UuidV6 must represent a version 6 (r
• Could not find a suitable builder for the provided codec and
• Expected version 1 (time-based) UUID

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