{"record":{"id":"0fe6f7d3812b8379","repo":"ramsey/uuid","slug":"static-node-value-cannot-be-greater-than-12-hexade","errorCode":null,"errorMessage":"Static node value cannot be greater than 12 hexadecimal characters","messagePattern":"Static node value cannot be greater than 12 hexadecimal characters","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Provider/Node/StaticNodeProvider.php","lineNumber":43,"sourceCode":"\nuse const STR_PAD_LEFT;\n\n/**\n * StaticNodeProvider provides a static node value with the multicast bit set\n *\n * @link https://www.rfc-editor.org/rfc/rfc9562#section-6.10 RFC 9562, 6.10. UUIDs That Do Not Identify the Host\n */\nclass StaticNodeProvider implements NodeProviderInterface\n{\n    private Hexadecimal $node;\n\n    /**\n     * @param Hexadecimal $node The static node value to use\n     */\n    public function __construct(Hexadecimal $node)\n    {\n        if (strlen($node->toString()) > 12) {\n            throw new InvalidArgumentException('Static node value cannot be greater than 12 hexadecimal characters');\n        }\n\n        $this->node = $this->setMulticastBit($node);\n    }\n\n    public function getNode(): Hexadecimal\n    {\n        return $this->node;\n    }\n\n    /**\n     * Set the multicast bit for the static node value\n     */\n    private function setMulticastBit(Hexadecimal $node): Hexadecimal\n    {\n        $nodeHex = str_pad($node->toString(), 12, '0', STR_PAD_LEFT);\n        $firstOctet = substr($nodeHex, 0, 2);\n        $firstOctet = str_pad(dechex(hexdec($firstOctet) | 0x01), 2, '0', STR_PAD_LEFT);","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Provider/Node/StaticNodeProvider.php#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Mask/truncate to 48 bits before constructing: substr(preg_replace('/[^0-9a-f]/i', '', $node), 0, 12)","Strip separators and prefixes from MAC addresses ('00:11:22:33:44:55' becomes '001122334455')","Left-pad shorter values to 12 with str_pad(..., 12, '0', STR_PAD_LEFT) if you need fixed width"],"exampleFix":"// before\n$provider = new \\Ramsey\\Uuid\\Provider\\Node\\StaticNodeProvider(\n    new \\Ramsey\\Uuid\\Type\\Hexadecimal('00:11:22:33:44:55')\n);\n\n// after\n$mac = preg_replace('/[^0-9a-f]/i', '', '00:11:22:33:44:55');\n$provider = new \\Ramsey\\Uuid\\Provider\\Node\\StaticNodeProvider(\n    new \\Ramsey\\Uuid\\Type\\Hexadecimal(strtolower($mac))\n);","handlingStrategy":"validation","validationCode":"$hex = strtolower(preg_replace('/[^0-9a-f]/i', '', $nodeString));\nif (strlen($hex) > 12) {\n    $hex = substr($hex, 0, 12); // 48-bit truncation, or throw if overflow is a bug\n}\n$provider = new \\Ramsey\\Uuid\\Provider\\Node\\StaticNodeProvider(\n    new \\Ramsey\\Uuid\\Type\\Hexadecimal($hex)\n);","typeGuard":"function isValidStaticNodeHex(string $hex): bool\n{\n    return preg_match('/^[0-9a-f]{1,12}$/i', $hex) === 1;\n}","tryCatchPattern":"try {\n    $provider = new \\Ramsey\\Uuid\\Provider\\Node\\StaticNodeProvider(new \\Ramsey\\Uuid\\Type\\Hexadecimal($node));\n} catch (\\Ramsey\\Uuid\\Exception\\InvalidArgumentException $e) {\n    // node exceeded 48 bits; normalize and retry\n    $provider = new \\Ramsey\\Uuid\\Provider\\Node\\StaticNodeProvider(\n        new \\Ramsey\\Uuid\\Type\\Hexadecimal(substr(preg_replace('/[^0-9a-f]/i', '', $node), 0, 12))\n    );\n}","preventionTips":["Strip colons, dashes, and 0x prefixes from MAC strings before use","Truncate derived fingerprints/hashes to 12 hex characters deliberately","Remember the provider sets the multicast bit itself; do not pre-set it"],"tags":["php","ramsey-uuid","node","static-node","mac-address","argument-validation","uuid-v1"],"backgroundTag":"invalid-node-value","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}