{"record":{"id":"9d78bb49a597b15c","repo":"ramsey/uuid","slug":"could-not-find-a-suitable-builder-for-the-provided","errorCode":null,"errorMessage":"Could not find a suitable builder for the provided codec and fields","messagePattern":"Could not find a suitable builder for the provided codec and fields","errorType":"exception","errorClass":"BuilderNotFoundException","httpStatus":null,"severity":"error","filePath":"src/Builder/FallbackBuilder.php","lineNumber":60,"sourceCode":"     * @return UuidInterface an instance of a UUID object\n     *\n     * @pure\n     */\n    public function build(CodecInterface $codec, string $bytes): UuidInterface\n    {\n        $lastBuilderException = null;\n\n        foreach ($this->builders as $builder) {\n            try {\n                return $builder->build($codec, $bytes);\n            } catch (UnableToBuildUuidException $exception) {\n                $lastBuilderException = $exception;\n\n                continue;\n            }\n        }\n\n        throw new BuilderNotFoundException(\n            'Could not find a suitable builder for the provided codec and fields',\n            0,\n            $lastBuilderException,\n        );\n    }\n}\n","sourceCodeStart":42,"sourceCodeEnd":67,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Builder/FallbackBuilder.php#L42-L67","documentation":"Thrown by FallbackBuilder::build() after it walked its whole builder list and every builder threw UnableToBuildUuidException. FallbackBuilder is a chain-of-responsibility builder (typically holding a BuilderCollection of DegradedUuidBuilder and Rfc4122UuidBuilder) that codecs call with the raw byte string. In practice the byte string itself was rejected by every builder - most often because it is not exactly 16 bytes (e.g. a 32-character hex string passed instead of raw binary).","triggerScenarios":"A UUID factory whose builder is a FallbackBuilder, then a decode path is fed bad bytes: $codec->decodeBytes($hexString) with a 32-char hex string, Uuid::fromBytes('') or truncated/oversized binary, or data read from a store that hex- or base64-encodes byte columns.","commonSituations":"Forgetting hex2bin() before fromBytes()/decodeBytes(); database abstraction returning hex for BINARY(16) columns (or the column actually being CHAR(32)/CHAR(36)); cache or queue round-trips that mangle binary payloads; empty input coerced to an empty string.","solutions":["Convert before decoding: $bytes = (string) hex2bin($hex); base64_decode($b64) if the transport is base64 - the result must be exactly 16 bytes.","Validate strlen($bytes) === 16 before calling fromBytes()/decodeBytes() and reject early.","Inspect $e->getPrevious() on the BuilderNotFoundException - it carries the last UnableToBuildUuidException and its reason.","Verify the FallbackBuilder was constructed with a non-empty BuilderCollection containing builders suited to your codec (Rfc4122UuidBuilder / DegradedUuidBuilder)."],"exampleFix":"// before\n$uuid = $factory->getCodec()->decodeBytes($row['uuid_hex']); // 32 hex chars -> BuilderNotFoundException\n\n// after\n$bytes = (string) hex2bin($row['uuid_hex']);\nassert(strlen($bytes) === 16);\n$uuid = $factory->getCodec()->decodeBytes($bytes);","handlingStrategy":"validation","validationCode":"function toUuidBytes(string $raw): string\n{\n    // Accept raw 16 bytes, or a 32-char hex string, and normalize.\n    if (strlen($raw) === 32 && ctype_xdigit($raw)) {\n        $raw = (string) hex2bin($raw);\n    }\n    if (strlen($raw) !== 16) {\n        throw new InvalidArgumentException('UUID byte string must be exactly 16 bytes');\n    }\n\n    return $raw;\n}\n\n$uuid = $codec->decodeBytes(toUuidBytes($value));","typeGuard":null,"tryCatchPattern":"try {\n    $uuid = $codec->decodeBytes($bytes);\n} catch (\\Ramsey\\Uuid\\Exception\\BuilderNotFoundException $e) {\n    $reason = $e->getPrevious(); // last UnableToBuildUuidException\n    // Treat as invalid stored data: log $reason, quarantine the row.\n    throw new StoredIdentifierCorruptException($row['id'], $reason);\n}","preventionTips":["Always hex2bin() hex strings and base64_decode() base64 strings before decodeBytes()/fromBytes().","Store UUIDs in BINARY(16) columns so length is fixed by the schema.","Assert strlen($bytes) === 16 in one shared normalization helper instead of at each call site.","Never pass user input directly to decode paths; validate shape first."],"tags":["php","ramsey-uuid","builder","fallback-builder","decode-bytes"],"backgroundTag":"uuid-bytes-decode-failed","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}