{"record":{"id":"322b8c5411292401","repo":"ramsey/uuid","slug":"the-byte-string-must-be-16-bytes-long-received-b-322b8c","errorCode":null,"errorMessage":"The byte string must be 16 bytes long; received {bytes} bytes","messagePattern":"The byte string must be 16 bytes long; received (.+?) bytes","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Nonstandard/Fields.php","lineNumber":56,"sourceCode":" *\n * Internally, this class represents the fields together as a 16-byte binary string.\n *\n * @immutable\n */\nfinal class Fields implements FieldsInterface\n{\n    use SerializableFieldsTrait;\n    use VariantTrait;\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     */\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\n    public function getBytes(): string\n    {\n        return $this->bytes;\n    }\n\n    public function getClockSeq(): Hexadecimal\n    {\n        $clockSeq = hexdec(bin2hex(substr($this->bytes, 8, 2))) & 0x3fff;\n\n        return new Hexadecimal(str_pad(dechex($clockSeq), 4, '0', STR_PAD_LEFT));\n    }\n\n    public function getClockSeqHiAndReserved(): Hexadecimal","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Nonstandard/Fields.php#L38-L74","documentation":"Nonstandard\\Fields is the lenient fields implementation used by Nonstandard\\UuidBuilder (the builder behind Ulid and other non-RFC layouts). It performs only one structural check: the byte string must be exactly 16 bytes (128 bits); variant and version are not validated. Any other length throws InvalidArgumentException.","triggerScenarios":"Calling Nonstandard\\UuidBuilder::build($codec, $bytes) (used by Ulid::fromString()/fromBytes internally) or constructing Nonstandard\\Fields directly with a byte string whose length differs from 16 — e.g. hex2bin('abc') on odd-length hex, a truncated ULID byte payload, or appending a prefix/suffix to the binary form.","commonSituations":"Custom codecs or builders for ULID/nonstandard identifiers; binary round-trips through columns or queues that truncate; passing hex strings where the API expects raw bytes.","solutions":["Verify strlen($bytes) === 16 before building; convert with exactly 32 hex chars","Use Ulid::fromString()/fromBytes() for ULID parsing so earlier validation gives clearer errors","Add a length assertion at your storage boundary (e.g. VARBINARY(16) columns)"],"exampleFix":"// before\n$ulid = \\Ramsey\\Uuid\\Nonstandard\\Ulid::fromBytes($value);\n\n// after\nif (strlen($value) !== 16) {\n    throw new InvalidArgumentException('ULID bytes must be 16, got ' . strlen($value));\n}\n$ulid = \\Ramsey\\Uuid\\Nonstandard\\Ulid::fromBytes($value);","handlingStrategy":"validation","validationCode":"if (strlen($bytes) !== 16) {\n    throw new InvalidArgumentException('Expected 16 bytes, got ' . strlen($bytes));\n}\n$ulid = \\Ramsey\\Uuid\\Nonstandard\\Ulid::fromBytes($bytes);","typeGuard":"function isSixteenByteString(string $bytes): bool\n{\n    return strlen($bytes) === 16;\n}","tryCatchPattern":"try {\n    $ulid = \\Ramsey\\Uuid\\Nonstandard\\Ulid::fromBytes($bytes);\n} catch (\\Ramsey\\Uuid\\Exception\\InvalidArgumentException $e) {\n    // length or upstream parse failure; re-fetch or reject the payload\n}","preventionTips":["Assert 16-byte length right after reading binary from storage","Validate hex strings are exactly 32 chars before hex2bin()","Use fixed-size binary columns for ULIDs"],"tags":["php","ramsey-uuid","ulid","nonstandard","binary-data","byte-length"],"backgroundTag":"invalid-uuid-byte-length","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}