apache/cassandra · error · RuntimeException

Cannot generate the node component of the UUID because…

Error message

Cannot generate the node component of the UUID because cannot retrieve any IP addresses.

What it means

TimeUUID.makeNode builds the 48-bit node component of generated v1 UUIDs by hashing all locally detected IP addresses. If getAllLocalAddresses() returns an empty set it cannot construct the node component and throws this RuntimeException.

Solutions

1. Configure at least one network interface (even loopback-assigned address) and bring it up
2. Check java.net.NetworkInterface enumeration in the environment (container --net settings, security manager)
3. Restart the JVM after networking is available — the node value is computed once per process
4. For isolated environments, patch/wrap getAllLocalAddresses to provide a deterministic fallback node id

Example fix

// before (no NIC) -> RuntimeException at UUID generation
// after
ip link set lo up && ip addr add 127.0.0.1/8 dev lo  # ensure at least one address, then restart JVM

boolean hasLocalAddress() { try { return java.net.NetworkInterface.getNetworkInterfaces().asIterator().hasNext(); } catch (Exception e) { return false; } }

try { TimeUUID.Generator.generateTimeUUIDBytes(); } catch (RuntimeException e) { if (e.getMessage().contains("cannot retrieve any IP addresses")) { /* configure networking or supply a fallback node id */ } else throw e; }

When it happens

Trigger: Calling TimeUUID generation (makeClockSeqAndNode → makeNode) on a machine where no network interfaces/addresses can be enumerated — no NICs up, restricted /proc or NetworkInterface enumeration failing, or a heavily sandboxed container with no addresses.

Common situations: Running Cassandra tooling/stress in minimal Docker or chroot environments without configured networking, unusual JVM security policies blocking NetworkInterface access, or hosts with all interfaces down at JVM startup.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Expected a string representation of a timeuuid, but got a
• Expected a string representation of a uuid, but got a
• Expected a string representation of a uuid, but got a
• Invalid table id
• Invalid UUID version

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/463d09ecfa625fa6. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/utils/TimeUUID.java:530

            return lsb;
        }

        private static long makeNode()
        {
            /*
             * We don't have access to the MAC address but need to generate a node part
             * that identify this host as uniquely as possible.
             * The spec says that one option is to take as many source that identify
             * this node as possible and hash them together. That's what we do here by
             * gathering all the ip of this host.
             * Note that FBUtilities.getJustBroadcastAddress() should be enough to uniquely
             * identify the node *in the cluster* but it triggers DatabaseDescriptor
             * instanciation and the UUID generator is used in Stress for instance,
             * where we don't want to require the yaml.
             */
            Collection<InetAddressAndPort> localAddresses = getAllLocalAddresses();
            if (localAddresses.isEmpty())
                throw new RuntimeException("Cannot generate the node component of the UUID because cannot retrieve any IP addresses.");

            // ideally, we'd use the MAC address, but java doesn't expose that.
            byte[] hash = hash(localAddresses);
            long node = 0;
            for (int i = 0; i < Math.min(6, hash.length); i++)
                node |= (0x00000000000000ff & (long)hash[i]) << (5-i)*8;
            assert (0xff00000000000000L & node) == 0;

            // Since we don't use the mac address, the spec says that multicast
            // bit (least significant bit of the first octet of the node ID) must be 1.
            return node | 0x0000010000000000L;
        }

        private static byte[] hash(Collection<InetAddressAndPort> data)
        {
            // Identify the host.
            Hasher hasher = Hashing.md5().newHasher();
            for(InetAddressAndPort addr : data)

View on GitHub (pinned to 88fd0f6a0e)