{"record":{"id":"8791bddde6f58770","repo":"ramsey/uuid","slug":"the-byte-string-must-be-16-bytes-long-received","errorCode":null,"errorMessage":"The byte string must be 16 bytes long; received {} bytes","messagePattern":"The byte string must be 16 bytes long; received (.+?) bytes","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Rfc4122/Fields.php","lineNumber":58,"sourceCode":"final class Fields implements FieldsInterface\n{\n    use MaxTrait;\n    use NilTrait;\n    use SerializableFieldsTrait;\n    use VariantTrait;\n    use VersionTrait;\n\n    /**\n     * @param string $bytes A 16-byte binary string representation of a UUID\n     *\n     * @throws InvalidArgumentException if the byte string is not exactly 16 bytes\n     * @throws InvalidArgumentException if the byte string does not represent an RFC 9562 (formerly RFC 4122) UUID\n     * @throws InvalidArgumentException if the byte string does not contain a valid version\n     */\n    public function __construct(private string $bytes)\n    {\n        if (strlen($this->bytes) !== 16) {\n            throw new InvalidArgumentException(\n                'The byte string must be 16 bytes long; ' . 'received ' . strlen($this->bytes) . ' bytes',\n            );\n        }\n\n        if (!$this->isCorrectVariant()) {\n            throw new InvalidArgumentException(\n                'The byte string received does not conform to the RFC 9562 (formerly RFC 4122) variant',\n            );\n        }\n\n        if (!$this->isCorrectVersion()) {\n            throw new InvalidArgumentException(\n                'The byte string received does not contain a valid RFC 9562 (formerly RFC 4122) version',\n            );\n        }\n    }\n\n    /**","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Rfc4122/Fields.php#L40-L76","documentation":"Rfc4122\\Fields is built by Rfc4122\\UuidBuilder for every standard UUID decode. Its first validation is structural: the binary representation must be exactly 16 bytes; any other length throws InvalidArgumentException before variant and version checks run. The two string-concatenated literal halves make this message easy to spot in logs.","triggerScenarios":"Constructing Rfc4122\\Fields directly or calling Rfc4122\\UuidBuilder::build($codec, $bytes) with bytes whose length is not 16 — hex2bin() of a hex string that is not exactly 32 chars, truncated binary payloads, or custom codecs that pass modified byte strings. The public Uuid::fromBytes() path usually throws a codec-level 16-character error first, so this fires mainly on custom/builder paths.","commonSituations":"Custom codecs or byte-mangling middleware (compression, encryption) changing payload length; BLOB columns with wrong size; unit tests constructing fields from hand-written byte strings.","solutions":["Assert strlen($bytes) === 16 before building fields or custom codec decode","When converting from hex, validate the hex is exactly 32 characters before hex2bin()","Use Uuid::fromString()/fromBytes() so the standard codecs validate with their own clear errors"],"exampleFix":"// before\n$uuid = $builder->build($codec, hex2bin($hex)); // $hex may be 30 chars\n\n// after\nif (strlen($hex) !== 32 || !ctype_xdigit($hex)) {\n    throw new InvalidArgumentException('UUID hex must be exactly 32 hex chars');\n}\n$uuid = $builder->build($codec, hex2bin($hex));","handlingStrategy":"validation","validationCode":"if (strlen($bytes) !== 16) {\n    throw new InvalidArgumentException('UUID bytes must be exactly 16, got ' . strlen($bytes));\n}\n$fields = new \\Ramsey\\Uuid\\Rfc4122\\Fields($bytes);","typeGuard":"function isSixteenByteString(string $bytes): bool\n{\n    return strlen($bytes) === 16;\n}","tryCatchPattern":"try {\n    $uuid = \\Ramsey\\Uuid\\Uuid::fromBytes($bytes);\n} catch (\\Ramsey\\Uuid\\Exception\\InvalidArgumentException $e) {\n    // '$bytes string should contain 16 characters.' from the codec, or fields error\n}","preventionTips":["Validate length once at the boundary where bytes enter your system","Never re-encode binary UUIDs through text channels without re-checking length","Use hex2bin only on validated 32-char hex strings"],"tags":["php","ramsey-uuid","binary-data","byte-length","rfc-9562","argument-validation"],"backgroundTag":"invalid-uuid-byte-length","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}