ramsey/uuid · error · ValueError

%s(): Argument #1 ($data) is invalid

Error message

%s(): Argument #1 ($data) is invalid

What it means

When PHP unserializes a Ramsey\Uuid\Type\Hexadecimal object, __unserialize(array $data) requires the array key 'string' (the shape produced by __serialize()). A missing key throws a native ValueError with a message styled after PHP's internal argument errors. The payload was not produced by this class's serialization, or was corrupted in storage/transit.

Source

Thrown at src/Type/Hexadecimal.php:106

    /**
     * Constructs the object from a serialized string representation
     *
     * @param string $data The serialized string representation of the object
     */
    public function unserialize(string $data): void
    {
        $this->__construct($data);
    }

    /**
     * @param array{string?: string} $data
     */
    public function __unserialize(array $data): void
    {
        // @codeCoverageIgnoreStart
        if (!isset($data['string'])) {
            throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));
        }
        // @codeCoverageIgnoreEnd

        $this->unserialize($data['string']);
    }

    /**
     * @return non-empty-string
     */
    private function prepareValue(string $value): string
    {
        $value = strtolower($value);

        if (str_starts_with($value, '0x')) {
            $value = substr($value, 2);
        }

        if (!preg_match('/^[A-Fa-f0-9]+$/', $value)) {

View on GitHub (pinned to da5b521600)

Solutions

  1. Rebuild instead of unserializing: $hex = new Hexadecimal($rawString)
  2. Flush the stale cache/session entries so fresh values are written
  3. Align library versions across all environments that read and write the shared store
  4. Store the plain hex string rather than the serialized object

Example fix

// before
$hex = unserialize($cachedValue); // array body missing 'string'
// ValueError: Ramsey\Uuid\Type\Hexadecimal::__unserialize(): Argument #1 ($data) is invalid

// after: persist the hex scalar and reconstruct
$hex = new Hexadecimal($cachedValue); // e.g. 'a1b2c3d4e5f6'
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate payload shape before unserializing
$decoded = unserialize($cached, ['allowed_classes' => false]);
if (!(is_array($decoded) && isset($decoded['string']))) {
    // treat as a miss; rebuild from raw hex
    $hex = new Ramsey\Uuid\Type\Hexadecimal($rawHex);
}

Try / catch

use Ramsey\Uuid\Type\Hexadecimal;

try {
    $hex = unserialize($cached);
} catch (\ValueError $e) {
    $hex = new Hexadecimal($rawHex); // rebuild from the source value
}

Prevention

When it happens

Trigger: unserialize() of a stored Hexadecimal payload whose array body lacks 'string' — hand-built serialized strings, cache entries from a differently-versioned producer, or truncated payloads.

Common situations: Caches (Redis/Memcached/APCu) or sessions holding values serialized by older code; payloads shared between systems with mismatched library expectations; corrupted serialized blobs after storage-level truncation.

Related errors

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