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

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)

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 char
• Expected version 1 (time-based) UUID
• Not a time-based UUID

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