ramsey/uuid · error · UnsupportedOperationException

The UUID version in the given fields is not supported by thi

Error message

The UUID version in the given fields is not supported by this UUID builder

What it means

Rfc4122\UuidBuilder::build() maps the fields' version to a concrete class (1=>UuidV1 ... 8=>UuidV8, plus NilUuid/MaxUuid). The default match arm throws UnsupportedOperationException for any version outside this set. Because Rfc4122\Fields itself rejects versions 0 and 9-f, this arm is effectively a guard for custom FieldsInterface implementations or custom builders that report exotic version numbers.

Source

Thrown at src/Rfc4122/UuidBuilder.php:102

                Uuid::UUID_TYPE_TIME => new UuidV1($fields, $this->numberConverter, $codec, $this->timeConverter),
                Uuid::UUID_TYPE_DCE_SECURITY
                    /** @phpstan-ignore possiblyImpure.new */
                    => new UuidV2($fields, $this->numberConverter, $codec, $this->timeConverter),
                /** @phpstan-ignore possiblyImpure.new */
                Uuid::UUID_TYPE_HASH_MD5 => new UuidV3($fields, $this->numberConverter, $codec, $this->timeConverter),
                /** @phpstan-ignore possiblyImpure.new */
                Uuid::UUID_TYPE_RANDOM => new UuidV4($fields, $this->numberConverter, $codec, $this->timeConverter),
                /** @phpstan-ignore possiblyImpure.new */
                Uuid::UUID_TYPE_HASH_SHA1 => new UuidV5($fields, $this->numberConverter, $codec, $this->timeConverter),
                Uuid::UUID_TYPE_REORDERED_TIME
                    /** @phpstan-ignore possiblyImpure.new */
                    => new UuidV6($fields, $this->numberConverter, $codec, $this->timeConverter),
                Uuid::UUID_TYPE_UNIX_TIME
                    /** @phpstan-ignore possiblyImpure.new */
                    => new UuidV7($fields, $this->numberConverter, $codec, $this->unixTimeConverter),
                /** @phpstan-ignore possiblyImpure.new */
                Uuid::UUID_TYPE_CUSTOM => new UuidV8($fields, $this->numberConverter, $codec, $this->timeConverter),
                default => throw new UnsupportedOperationException(
                    'The UUID version in the given fields is not supported by this UUID builder',
                ),
            };
        } catch (Throwable $e) {
            /** @phpstan-ignore possiblyImpure.methodCall, possiblyImpure.methodCall */
            throw new UnableToBuildUuidException($e->getMessage(), (int) $e->getCode(), $e);
        }
    }

    /**
     * Proxy method to allow injecting a mock for testing
     *
     * @pure
     */
    protected function buildFields(string $bytes): FieldsInterface
    {
        /** @phpstan-ignore possiblyImpure.new */
        return new Fields($bytes);

View on GitHub (pinned to da5b521600)

Solutions

1. Ensure your custom fields report a version in 1-8 (or use the standard Rfc4122\Fields)
2. Map unknown versions to UuidV8 (UUID_TYPE_CUSTOM) — that is the RFC 9562 escape hatch for custom layouts
3. Subclass Rfc4122\UuidBuilder and extend the match with your version instead of letting it fall to default

Example fix

// before (custom fields)
public function getVersion(): ?int { return 9; }

// after
public function getVersion(): ?int { return 8; } // custom layout uses v8
// or in your builder:
match ($fields->getVersion()) {
    9 => new MyUuidV9($fields, ...),
    default => parent::build($codec, $bytes),
};

$version = $fields->getVersion();
if (!in_array($version, [1, 2, 3, 4, 5, 6, 7, 8], true)) {
    $version = 8; // remap custom layouts to RFC 9562 version 8
}
// then build via a builder that maps that version

function isBuildableVersion(?int $version): bool
{
    return $version !== null && $version >= 1 && $version <= 8;
}

try {
    $uuid = $builder->build($codec, $bytes);
} catch (\Ramsey\Uuid\Exception\UnableToBuildUuidException $e) {
    $prev = $e->getPrevious();
    if ($prev instanceof \Ramsey\Uuid\Exception\UnsupportedOperationException) {
        // fields reported a version this builder cannot map
    }
}

When it happens

Trigger: Using a custom FieldsInterface/BuilderFields implementation whose getVersion() returns something not in {1,2,3,4,5,6,7,8} (e.g. 0, 9, or null mishandling), or a custom UuidBuilder subclass that alters the version mapping and falls through to the default arm.

Common situations: Extending ramsey/uuid with custom field layouts or experimental UUID versions; bugs in custom builders computing the version nibble; upgrading custom code that assumed older version enums.

Related errors

• The byte string received does not contain a valid version
• The byte string received does not contain a valid RFC 9562 (
• The byte string must be 16 bytes long; received {} bytes
• The byte string received does not conform to the RFC 9562 (f
• $e->getMessage()

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