ramsey/uuid · error · InvalidArgumentException

Static node value cannot be greater than 12 hexadecimal char

Error message

Static node value cannot be greater than 12 hexadecimal characters

What it means

StaticNodeProvider pins a fixed node value for UUID versions 1 and 6 (RFC 9562 section 6.10 'UUIDs That Do Not Identify the Host'). A node is exactly 48 bits, so the hexadecimal string must be at most 12 hex characters; anything longer throws InvalidArgumentException before the multicast bit is set.

Source

Thrown at src/Provider/Node/StaticNodeProvider.php:43

use const STR_PAD_LEFT;

/**
 * StaticNodeProvider provides a static node value with the multicast bit set
 *
 * @link https://www.rfc-editor.org/rfc/rfc9562#section-6.10 RFC 9562, 6.10. UUIDs That Do Not Identify the Host
 */
class StaticNodeProvider implements NodeProviderInterface
{
    private Hexadecimal $node;

    /**
     * @param Hexadecimal $node The static node value to use
     */
    public function __construct(Hexadecimal $node)
    {
        if (strlen($node->toString()) > 12) {
            throw new InvalidArgumentException('Static node value cannot be greater than 12 hexadecimal characters');
        }

        $this->node = $this->setMulticastBit($node);
    }

    public function getNode(): Hexadecimal
    {
        return $this->node;
    }

    /**
     * Set the multicast bit for the static node value
     */
    private function setMulticastBit(Hexadecimal $node): Hexadecimal
    {
        $nodeHex = str_pad($node->toString(), 12, '0', STR_PAD_LEFT);
        $firstOctet = substr($nodeHex, 0, 2);
        $firstOctet = str_pad(dechex(hexdec($firstOctet) | 0x01), 2, '0', STR_PAD_LEFT);

View on GitHub (pinned to da5b521600)

Solutions

1. Mask/truncate to 48 bits before constructing: substr(preg_replace('/[^0-9a-f]/i', '', $node), 0, 12)
2. Strip separators and prefixes from MAC addresses ('00:11:22:33:44:55' becomes '001122334455')
3. Left-pad shorter values to 12 with str_pad(..., 12, '0', STR_PAD_LEFT) if you need fixed width

Example fix

// before
$provider = new \Ramsey\Uuid\Provider\Node\StaticNodeProvider(
    new \Ramsey\Uuid\Type\Hexadecimal('00:11:22:33:44:55')
);

// after
$mac = preg_replace('/[^0-9a-f]/i', '', '00:11:22:33:44:55');
$provider = new \Ramsey\Uuid\Provider\Node\StaticNodeProvider(
    new \Ramsey\Uuid\Type\Hexadecimal(strtolower($mac))
);

$hex = strtolower(preg_replace('/[^0-9a-f]/i', '', $nodeString));
if (strlen($hex) > 12) {
    $hex = substr($hex, 0, 12); // 48-bit truncation, or throw if overflow is a bug
}
$provider = new \Ramsey\Uuid\Provider\Node\StaticNodeProvider(
    new \Ramsey\Uuid\Type\Hexadecimal($hex)
);

function isValidStaticNodeHex(string $hex): bool
{
    return preg_match('/^[0-9a-f]{1,12}$/i', $hex) === 1;
}

try {
    $provider = new \Ramsey\Uuid\Provider\Node\StaticNodeProvider(new \Ramsey\Uuid\Type\Hexadecimal($node));
} catch (\Ramsey\Uuid\Exception\InvalidArgumentException $e) {
    // node exceeded 48 bits; normalize and retry
    $provider = new \Ramsey\Uuid\Provider\Node\StaticNodeProvider(
        new \Ramsey\Uuid\Type\Hexadecimal(substr(preg_replace('/[^0-9a-f]/i', '', $node), 0, 12))
    );
}

When it happens

Trigger: new StaticNodeProvider(new Hexadecimal($node)) where strlen($node->toString()) > 12 — e.g. passing a full UUID hex (32 chars), a hex string with separators like '00:11:22:33:44:55' (17 chars), a '0x'-prefixed value, or an untruncated machine-fingerprint hash.

Common situations: Deriving a stable node from a hostname/container-ID hash and forgetting to truncate to 12 hex chars; copying MAC strings with colons or dashes; passing the string form of a UUID as the node.

Related errors

• Invalid node value
• Unable to find a suitable node provider
• Unable to fetch a node for this system
• Fields used to create a UuidV1 must represent a version 1 (t
• Expected version 1 (time-based) UUID

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