ramsey/uuid · error · InvalidArgumentException

The byte string must be 16 bytes long; received {bytes} byte

Error message

The byte string must be 16 bytes long; received {bytes} bytes

What it means

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.

Source

Thrown at src/Guid/Fields.php:64

final class Fields implements FieldsInterface
{
    use MaxTrait;
    use NilTrait;
    use SerializableFieldsTrait;
    use VariantTrait;
    use VersionTrait;

    /**
     * @param string $bytes A 16-byte binary string representation of a UUID
     *
     * @throws InvalidArgumentException if the byte string is not exactly 16 bytes
     * @throws InvalidArgumentException if the byte string does not represent a GUID
     * @throws InvalidArgumentException if the byte string does not contain a valid version
     */
    public function __construct(private string $bytes)
    {
        if (strlen($this->bytes) !== 16) {
            throw new InvalidArgumentException(
                'The byte string must be 16 bytes long; received ' . strlen($this->bytes) . ' bytes',
            );
        }

        if (!$this->isCorrectVariant()) {
            throw new InvalidArgumentException(
                'The byte string received does not conform to the RFC 9562 (formerly RFC 4122) '
                . 'or Microsoft Corporation variants',
            );
        }

        if (!$this->isCorrectVersion()) {
            throw new InvalidArgumentException('The byte string received does not contain a valid version');
        }
    }

    public function getBytes(): string
    {

View on GitHub (pinned to da5b521600)

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()

Example fix

// before
$fields = new \Ramsey\Uuid\Guid\Fields($blob); // may be 15 bytes

// after
if (strlen($blob) !== 16) {
    throw new InvalidArgumentException('Expected 16 bytes, got ' . strlen($blob));
}
$fields = new \Ramsey\Uuid\Guid\Fields($blob);

Defensive patterns

Strategy: validation

Validate before calling

if (strlen($bytes) !== 16) {
    throw new InvalidArgumentException('GUID bytes must be 16, got ' . strlen($bytes));
}
$fields = new \Ramsey\Uuid\Guid\Fields($bytes);

Type guard

function isGuidByteString(string $bytes): bool
{
    return strlen($bytes) === 16;
}

Try / catch

try {
    $guid = \Ramsey\Uuid\Guid\Guid::fromBytes($bytes);
} catch (\Ramsey\Uuid\Exception\UnableToBuildUuidException $e) {
    // message carries the underlying length/variant/version error
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of ramsey/uuid@da5b521600 (2026-08-21). Data as JSON: /api/errors/9de4d1a4e367a072. Report an issue: GitHub.