{"record":{"id":"c068b52fb98203d1","repo":"ramsey/uuid","slug":"the-uuid-version-in-the-given-fields-is-not-suppor","errorCode":null,"errorMessage":"The UUID version in the given fields is not supported by this UUID builder","messagePattern":"The UUID version in the given fields is not supported by this UUID builder","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"src/Rfc4122/UuidBuilder.php","lineNumber":102,"sourceCode":"                Uuid::UUID_TYPE_TIME => new UuidV1($fields, $this->numberConverter, $codec, $this->timeConverter),\n                Uuid::UUID_TYPE_DCE_SECURITY\n                    /** @phpstan-ignore possiblyImpure.new */\n                    => new UuidV2($fields, $this->numberConverter, $codec, $this->timeConverter),\n                /** @phpstan-ignore possiblyImpure.new */\n                Uuid::UUID_TYPE_HASH_MD5 => new UuidV3($fields, $this->numberConverter, $codec, $this->timeConverter),\n                /** @phpstan-ignore possiblyImpure.new */\n                Uuid::UUID_TYPE_RANDOM => new UuidV4($fields, $this->numberConverter, $codec, $this->timeConverter),\n                /** @phpstan-ignore possiblyImpure.new */\n                Uuid::UUID_TYPE_HASH_SHA1 => new UuidV5($fields, $this->numberConverter, $codec, $this->timeConverter),\n                Uuid::UUID_TYPE_REORDERED_TIME\n                    /** @phpstan-ignore possiblyImpure.new */\n                    => new UuidV6($fields, $this->numberConverter, $codec, $this->timeConverter),\n                Uuid::UUID_TYPE_UNIX_TIME\n                    /** @phpstan-ignore possiblyImpure.new */\n                    => new UuidV7($fields, $this->numberConverter, $codec, $this->unixTimeConverter),\n                /** @phpstan-ignore possiblyImpure.new */\n                Uuid::UUID_TYPE_CUSTOM => new UuidV8($fields, $this->numberConverter, $codec, $this->timeConverter),\n                default => throw new UnsupportedOperationException(\n                    'The UUID version in the given fields is not supported by this UUID builder',\n                ),\n            };\n        } catch (Throwable $e) {\n            /** @phpstan-ignore possiblyImpure.methodCall, possiblyImpure.methodCall */\n            throw new UnableToBuildUuidException($e->getMessage(), (int) $e->getCode(), $e);\n        }\n    }\n\n    /**\n     * Proxy method to allow injecting a mock for testing\n     *\n     * @pure\n     */\n    protected function buildFields(string $bytes): FieldsInterface\n    {\n        /** @phpstan-ignore possiblyImpure.new */\n        return new Fields($bytes);","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Rfc4122/UuidBuilder.php#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure your custom fields report a version in 1-8 (or use the standard Rfc4122\\Fields)","Map unknown versions to UuidV8 (UUID_TYPE_CUSTOM) — that is the RFC 9562 escape hatch for custom layouts","Subclass Rfc4122\\UuidBuilder and extend the match with your version instead of letting it fall to default"],"exampleFix":"// before (custom fields)\npublic function getVersion(): ?int { return 9; }\n\n// after\npublic function getVersion(): ?int { return 8; } // custom layout uses v8\n// or in your builder:\nmatch ($fields->getVersion()) {\n    9 => new MyUuidV9($fields, ...),\n    default => parent::build($codec, $bytes),\n};","handlingStrategy":"validation","validationCode":"$version = $fields->getVersion();\nif (!in_array($version, [1, 2, 3, 4, 5, 6, 7, 8], true)) {\n    $version = 8; // remap custom layouts to RFC 9562 version 8\n}\n// then build via a builder that maps that version","typeGuard":"function isBuildableVersion(?int $version): bool\n{\n    return $version !== null && $version >= 1 && $version <= 8;\n}","tryCatchPattern":"try {\n    $uuid = $builder->build($codec, $bytes);\n} catch (\\Ramsey\\Uuid\\Exception\\UnableToBuildUuidException $e) {\n    $prev = $e->getPrevious();\n    if ($prev instanceof \\Ramsey\\Uuid\\Exception\\UnsupportedOperationException) {\n        // fields reported a version this builder cannot map\n    }\n}","preventionTips":["Make custom FieldsInterface implementations report versions 1-8","Use version 8 (custom) for nonstandard layouts instead of undefined numbers","Extend Rfc4122\\UuidBuilder rather than bypassing its version match"],"tags":["php","ramsey-uuid","uuid-builder","version-nibble","custom-implementation","rfc-9562"],"backgroundTag":"unsupported-uuid-version","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}