{"record":{"id":"d65eef20332d5318","repo":"ramsey/uuid","slug":"unable-to-fetch-a-node-for-this-system","errorCode":null,"errorMessage":"Unable to fetch a node for this system","messagePattern":"Unable to fetch a node for this system","errorType":"exception","errorClass":"NodeException","httpStatus":null,"severity":"error","filePath":"src/Provider/Node/SystemNodeProvider.php","lineNumber":61,"sourceCode":" */\nclass SystemNodeProvider implements NodeProviderInterface\n{\n    /**\n     * Pattern to match nodes in `ifconfig` and `ipconfig` output.\n     */\n    private const IFCONFIG_PATTERN = '/[^:]([0-9a-f]{2}([:-])[0-9a-f]{2}(\\2[0-9a-f]{2}){4})[^:]/i';\n\n    /**\n     * Pattern to match nodes in sysfs stream output.\n     */\n    private const SYSFS_PATTERN = '/^([0-9a-f]{2}:){5}[0-9a-f]{2}$/i';\n\n    public function getNode(): Hexadecimal\n    {\n        $node = $this->getNodeFromSystem();\n\n        if ($node === '') {\n            throw new NodeException('Unable to fetch a node for this system');\n        }\n\n        return new Hexadecimal($node);\n    }\n\n    /**\n     * Returns the system node if found\n     */\n    protected function getNodeFromSystem(): string\n    {\n        /** @var string | null $node */\n        static $node = null;\n\n        if ($node !== null) {\n            return $node;\n        }\n\n        // First, try a Linux-specific approach.","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Provider/Node/SystemNodeProvider.php#L43-L79","documentation":"SystemNodeProvider tries to find the host MAC address two ways: reading /sys/class/net/*/address (Linux sysfs) and parsing ipconfig/ifconfig/netstat output via passthru. All-zero addresses and non-matching lines are filtered out; when every avenue returns an empty string, getNode() throws NodeException('Unable to fetch a node for this system'). The empty result is memoized in a static, so retries in the same process keep failing.","triggerScenarios":"Calling (new SystemNodeProvider())->getNode() or Uuid::uuid1() with a custom feature set that uses SystemNodeProvider alone, on a host where /sys/class/net is absent/unreadable, only loopback exists (00:00:00:00:00:00 is filtered), or passthru is disabled by disable_functions so the command fallback never runs. The default factory setup avoids this by falling back to RandomNodeProvider.","commonSituations":"Minimal Docker/distroless containers without sysfs or netstat/ifconfig; macOS/Windows where the command output format differs or tools are missing; hardened PHP with passthru in disable_functions; VMs with MAC-less virtual interfaces.","solutions":["Rely on the default fallback chain ([SystemNodeProvider, RandomNodeProvider]) instead of SystemNodeProvider alone","Pass an explicit node to Uuid::uuid1(null, null, $node) or register a StaticNodeProvider with a chosen 12-hex value","In containers, ensure /sys/class/net/*/address is readable or accept random nodes (RFC 9562 permits them)"],"exampleFix":"// before\n$node = (new \\Ramsey\\Uuid\\Provider\\Node\\SystemNodeProvider())->getNode();\n\n// after\nuse Ramsey\\Uuid\\Provider\\Node\\FallbackNodeProvider;\nuse Ramsey\\Uuid\\Provider\\Node\\SystemNodeProvider;\nuse Ramsey\\Uuid\\Provider\\Node\\RandomNodeProvider;\n$fallback = new FallbackNodeProvider([new SystemNodeProvider(), new RandomNodeProvider()]);\n$node = $fallback->getNode(); // never throws unless both fail","handlingStrategy":"fallback","validationCode":"$sysfs = glob('/sys/class/net/*/address');\n$hasMac = false;\nforeach ((array) $sysfs as $p) {\n    $mac = trim((string) @file_get_contents($p));\n    if (preg_match('/^([0-9a-f]{2}:){5}[0-9a-f]{2}$/i', $mac) && $mac !== '00:00:00:00:00:00') {\n        $hasMac = true;\n        break;\n    }\n}\n$node = $hasMac ? null : new \\Ramsey\\Uuid\\Type\\Hexadecimal('0200deadbeef'); // static fallback","typeGuard":null,"tryCatchPattern":"try {\n    $node = (new \\Ramsey\\Uuid\\Provider\\Node\\SystemNodeProvider())->getNode();\n} catch (\\Ramsey\\Uuid\\Exception\\NodeException $e) {\n    // no readable MAC on this host; fall back to random node\n    $node = (new \\Ramsey\\Uuid\\Provider\\Node\\RandomNodeProvider())->getNode();\n}","preventionTips":["Do not configure SystemNodeProvider alone; use the default fallback chain","Ensure /sys/class/net/*/address is readable in containers (mount sysfs)","Note the lookup is memoized: fixing env requires a new process"],"tags":["php","ramsey-uuid","mac-address","sysfs","ifconfig","containers","uuid-v1","environment"],"backgroundTag":"mac-address-lookup-failed","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}