{"record":{"id":"e0e741be29e9a847","repo":"ramsey/uuid","slug":"unable-to-find-a-suitable-node-provider","errorCode":null,"errorMessage":"Unable to find a suitable node provider","messagePattern":"Unable to find a suitable node provider","errorType":"exception","errorClass":"NodeException","httpStatus":null,"severity":"error","filePath":"src/Provider/Node/FallbackNodeProvider.php","lineNumber":47,"sourceCode":"    public function __construct(private iterable $providers)\n    {\n    }\n\n    public function getNode(): Hexadecimal\n    {\n        $lastProviderException = null;\n\n        foreach ($this->providers as $provider) {\n            try {\n                return $provider->getNode();\n            } catch (NodeException $exception) {\n                $lastProviderException = $exception;\n\n                continue;\n            }\n        }\n\n        throw new NodeException(message: 'Unable to find a suitable node provider', previous: $lastProviderException);\n    }\n}\n","sourceCodeStart":29,"sourceCodeEnd":50,"githubUrl":"https://github.com/ramsey/uuid/blob/da5b521600a707d2dd097598464bd3090de850f5/src/Provider/Node/FallbackNodeProvider.php#L29-L50","documentation":"FallbackNodeProvider iterates its provider collection and returns the first successful getNode(); every failure is a NodeException. If all providers throw, it re-throws NodeException('Unable to find a suitable node provider') with the last exception chained as previous. The default feature set wires [SystemNodeProvider, RandomNodeProvider], so failing both means no system MAC was found AND the random fallback also failed (or you configured your own provider list that exhausted).","triggerScenarios":"Uuid::uuid1() with the default setup on a host where SystemNodeProvider finds no MAC and RandomNodeProvider's random_bytes/refresh calls fail; or a custom FallbackNodeProvider / NodeProviderCollection whose members all throw — e.g. [SystemNodeProvider] alone in a container with no usable NIC.","commonSituations":"Containers/VMs with only loopback or MAC-less interfaces; sysfs not mounted and ifconfig/netstat output empty or in unexpected locale/format; passthru disabled so getIfconfig() returns ''; hardened CSPRNG failing in restricted runtimes.","solutions":["Inspect getPrevious() to see which underlying lookup failed, then fix that (mount /sys/class/net readable, enable passthru, provide an interface)","Pass a node explicitly: Uuid::uuid1(null, null, $nodeHexadecimal), or use a StaticNodeProvider/RandomNodeProvider in your fallback chain","If node identity is not required, use Uuid::uuid4()/uuid7() which need no node at all"],"exampleFix":"// before\n$factory = new \\Ramsey\\Uuid\\UuidFactory(new \\Ramsey\\Uuid\\FeatureSet());\n$uuid = $factory->uuid1(); // only SystemNodeProvider configured, no NIC\n\n// after\n$nodeProvider = new \\Ramsey\\Uuid\\Provider\\Node\\FallbackNodeProvider([\n    new \\Ramsey\\Uuid\\Provider\\Node\\SystemNodeProvider(),\n    new \\Ramsey\\Uuid\\Provider\\Node\\RandomNodeProvider(),\n]);\n$uuid = \\Ramsey\\Uuid\\Uuid::uuid1(null, null, $nodeProvider->getNode());","handlingStrategy":"fallback","validationCode":"use Ramsey\\Uuid\\Provider\\Node\\FallbackNodeProvider;\nuse Ramsey\\Uuid\\Provider\\Node\\SystemNodeProvider;\nuse Ramsey\\Uuid\\Provider\\Node\\RandomNodeProvider;\n\n$provider = new FallbackNodeProvider([\n    new SystemNodeProvider(),\n    new RandomNodeProvider(), // guarantees a node when sysfs/ifconfig fail\n]);\n$node = $provider->getNode(); // safe to call","typeGuard":null,"tryCatchPattern":"try {\n    $node = $provider->getNode();\n} catch (\\Ramsey\\Uuid\\Exception\\NodeException $e) {\n    $root = $e->getPrevious(); // which provider failed last and why\n    $node = new \\Ramsey\\Uuid\\Type\\Hexadecimal('0200deadbeef'); // pinned fallback node\n}","preventionTips":["Always end custom provider chains with RandomNodeProvider","Log getPrevious() to identify the failing provider in diagnostics","For node-less environments, prefer uuid4/uuid7"],"tags":["php","ramsey-uuid","node-provider","mac-address","containers","fallback-chain","uuid-v1"],"backgroundTag":"mac-address-lookup-failed","analyzedSha":"da5b521600a707d2dd097598464bd3090de850f5","analyzedAt":"2026-08-21T01:35:29.252Z","schemaVersion":2},"datasetVersion":"2026-08-21T03:17:12.404Z"}