ramsey/uuid · error · NodeException

Unable to find a suitable node provider

Error message

Unable to find a suitable node provider

What it means

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).

Solutions

1. Inspect getPrevious() to see which underlying lookup failed, then fix that (mount /sys/class/net readable, enable passthru, provide an interface)
2. Pass a node explicitly: Uuid::uuid1(null, null, $nodeHexadecimal), or use a StaticNodeProvider/RandomNodeProvider in your fallback chain
3. If node identity is not required, use Uuid::uuid4()/uuid7() which need no node at all

Example fix

// before
$factory = new \Ramsey\Uuid\UuidFactory(new \Ramsey\Uuid\FeatureSet());
$uuid = $factory->uuid1(); // only SystemNodeProvider configured, no NIC

// after
$nodeProvider = new \Ramsey\Uuid\Provider\Node\FallbackNodeProvider([
    new \Ramsey\Uuid\Provider\Node\SystemNodeProvider(),
    new \Ramsey\Uuid\Provider\Node\RandomNodeProvider(),
]);
$uuid = \Ramsey\Uuid\Uuid::uuid1(null, null, $nodeProvider->getNode());

use Ramsey\Uuid\Provider\Node\FallbackNodeProvider;
use Ramsey\Uuid\Provider\Node\SystemNodeProvider;
use Ramsey\Uuid\Provider\Node\RandomNodeProvider;

$provider = new FallbackNodeProvider([
    new SystemNodeProvider(),
    new RandomNodeProvider(), // guarantees a node when sysfs/ifconfig fail
]);
$node = $provider->getNode(); // safe to call

try {
    $node = $provider->getNode();
} catch (\Ramsey\Uuid\Exception\NodeException $e) {
    $root = $e->getPrevious(); // which provider failed last and why
    $node = new \Ramsey\Uuid\Type\Hexadecimal('0200deadbeef'); // pinned fallback node
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to fetch a node for this system
• Invalid node value
• Static node value cannot be greater than 12 hexadecimal…
• Expected version 1 (time-based) UUID
• Fields used to create a UuidV1 must represent a version 1…

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

Appendix: source

Thrown at src/Provider/Node/FallbackNodeProvider.php:47

    public function __construct(private iterable $providers)
    {
    }

    public function getNode(): Hexadecimal
    {
        $lastProviderException = null;

        foreach ($this->providers as $provider) {
            try {
                return $provider->getNode();
            } catch (NodeException $exception) {
                $lastProviderException = $exception;

                continue;
            }
        }

        throw new NodeException(message: 'Unable to find a suitable node provider', previous: $lastProviderException);
    }
}

View on GitHub (pinned to da5b521600)