What causes "Invalid node value" in ramsey/uuid?

Strip separators and prefixes: $node = str_replace([':', '-', '0x'], '', strtolower(trim($mac))).

ramsey/uuid · error · InvalidArgumentException

Invalid node value

Error message

Invalid node value

What it means

DefaultTimeGenerator::getValidNode() accepts the node as null (from the node provider), an int, or a hex string, but requires it to match /^[A-Fa-f0-9]+$/ and be at most 12 hex digits (48 bits); otherwise it throws InvalidArgumentException('Invalid node value').

Source

Thrown at src/Generator/DefaultTimeGenerator.php:113

     * @param int | string | null $node A node value that may be used to override the node provider
     *
     * @return string 6-byte binary string representation of the node
     *
     * @throws InvalidArgumentException
     */
    private function getValidNode(int | string | null $node): string
    {
        if ($node === null) {
            $node = $this->nodeProvider->getNode();
        }

        // Convert the node to hex if it is still an integer.
        if (is_int($node)) {
            $node = dechex($node);
        }

        if (!preg_match('/^[A-Fa-f0-9]+$/', (string) $node) || strlen((string) $node) > 12) {
            throw new InvalidArgumentException('Invalid node value');
        }

        return (string) hex2bin(str_pad((string) $node, 12, '0', STR_PAD_LEFT));
    }
}

View on GitHub (pinned to da5b521600)

Solutions

Strip separators and prefixes: $node = str_replace([':', '-', '0x'], '', strtolower(trim($mac))).
Pass 12 hex digits, or a non-negative int <= 281474976710655 (0xffffffffffff).
Wrap the node in Ramsey\Uuid\Type\Hexadecimal at construction so format expectations are explicit.

Example fix

// before
$uuid = Uuid::uuid1($nodeProvider, null, $macAddress); // '3c:22:fb:1a:2b:3c' -> InvalidArgumentException

// after
$node = str_replace([':', '-'], '', trim($macAddress)); // '3c22fb1a2b3c'
$uuid = Uuid::uuid1(null, null, $node);

Defensive patterns

Strategy: validation

Validate before calling

function normalizeNode(string|int|null $node): ?string
{
    if ($node === null) {
        return null;
    }
    $hex = is_int($node)
        ? dechex($node)
        : strtolower(str_replace([':', '-', '0x'], '', trim($node)));

    if (!preg_match('/^[a-f0-9]{1,12}$/', $hex)) {
        throw new InvalidArgumentException(sprintf('invalid node value: %s', (string) $node));
    }

    return $hex;
}

$uuid = Uuid::uuid1(null, null, normalizeNode($configuredNode));

Type guard

function isUsableNodeValue(string|int $node): bool
{
    $hex = is_int($node) ? dechex($node) : $node;

    return (bool) preg_match('/^[A-Fa-f0-9]{1,12}$/', $hex);
}

Try / catch

try {
    $uuid = Uuid::uuid1($nodeProvider, null, $node);
} catch (\Ramsey\Uuid\Exception\InvalidArgumentException $e) {
    $uuid = Uuid::uuid1(); // regenerate with the provider's node
}

Prevention

Strip ':', '-' and '0x' from MAC addresses before passing them as node.
Pass at most 12 hex digits or an int <= 281474976710655; negative ints always fail.
Wrap node config in a Hexadecimal type to make the format explicit.
Validate node values once where they enter configuration, not at each uuid1() call.

When it happens

Trigger: Passing a MAC address with separators to Uuid::uuid1($node) ('00:11:22:33:44:55' or '00-11-22-33-44-55'); a node with '0x' prefix or whitespace; a negative int (dechex(-1) produces 16 hex chars); any int/string above 0xffffffffffff.

Common situations: Formatting a MAC from config, ifconfig, or a cloud metadata service without stripping separators; passing 64-bit ints as node; copy/pasting node values with newlines from config files.

Related errors

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