{"record":{"id":"9de4d1a4e367a072","repo":"ramsey/uuid","slug":"the-byte-string-must-be-16-bytes-long-received-b","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/Guid/Fields.php","lineNumber":64,"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 a GUID\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) '\n                . 'or Microsoft Corporation variants',\n            );\n        }\n\n        if (!$this->isCorrectVersion()) {\n            throw new InvalidArgumentException('The byte string received does not contain a valid version');\n        }\n    }\n\n    public function getBytes(): string\n    {","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Guid/Fields.php#L46-L82","documentation":"Guid\\Fields is the fields object ramsey/uuid constructs when decoding a Microsoft-style GUID (little-endian byte order, via GuidStringCodec and GuidBuilder). Its constructor first enforces the RFC 9562 layout requirement that a UUID be exactly 16 bytes; any other length throws InvalidArgumentException before variant/version are even checked.","triggerScenarios":"Constructing Ramsey\\Uuid\\Guid\\Fields directly, or a custom codec/builder calling GuidBuilder::build($codec, $bytes) with a byte string that is not 16 bytes — e.g. truncated binary from a database BLOB, hex2bin() applied to an odd-length or short hex string, or passing a 32-character hex string where raw bytes are expected.","commonSituations":"Custom GUID codecs in .NET/COM/SQL Server interop code; double-encoding bugs (hex vs. binary confusion); storing UUIDs in variable-length binary columns and reading back truncated values.","solutions":["Check strlen($bytes) === 16 before constructing the fields or calling a builder","Prefer Guid::fromString() / Guid::fromBytes(), which validate length earlier with clearer errors","If converting from hex, ensure exactly 32 hex characters before hex2bin()"],"exampleFix":"// before\n$fields = new \\Ramsey\\Uuid\\Guid\\Fields($blob); // may be 15 bytes\n\n// after\nif (strlen($blob) !== 16) {\n    throw new InvalidArgumentException('Expected 16 bytes, got ' . strlen($blob));\n}\n$fields = new \\Ramsey\\Uuid\\Guid\\Fields($blob);","handlingStrategy":"validation","validationCode":"if (strlen($bytes) !== 16) {\n    throw new InvalidArgumentException('GUID bytes must be 16, got ' . strlen($bytes));\n}\n$fields = new \\Ramsey\\Uuid\\Guid\\Fields($bytes);","typeGuard":"function isGuidByteString(string $bytes): bool\n{\n    return strlen($bytes) === 16;\n}","tryCatchPattern":"try {\n    $guid = \\Ramsey\\Uuid\\Guid\\Guid::fromBytes($bytes);\n} catch (\\Ramsey\\Uuid\\Exception\\UnableToBuildUuidException $e) {\n    // message carries the underlying length/variant/version error\n}","preventionTips":["Use BINARY(16)/VARBINARY(16) columns so length is fixed at the storage layer","Keep hex and binary representations strictly separated in your codebase","Prefer Guid::fromString()/fromBytes() over constructing fields directly"],"tags":["php","ramsey-uuid","guid","binary-data","byte-length","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"}