apache/cassandra · critical · ConfigurationException

Configured ${configName} "${intf}" could not be found

Error message

Configured ${configName} "${intf}" could not be found

What it means

DatabaseDescriptor.getNetworkInterfaceAddress resolves a configured interface name (for listen/broadcast/rpc addresses) via java.net.NetworkInterface.getByName. If no interface with that name exists on the host, a ConfigurationException is thrown before Cassandra can bind.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:542

                                     : FBUtilities.construct(loaderClass, "configuration loading", ConfigurationLoader.class);
        Config config = loader.loadConfig();

        if (!hasLoggedConfig)
        {
            hasLoggedConfig = true;
            Config.log(config);
        }

        return config;
    }

    private static InetAddress getNetworkInterfaceAddress(String intf, String configName, boolean preferIPv6) throws ConfigurationException
    {
        try
        {
            NetworkInterface ni = NetworkInterface.getByName(intf);
            if (ni == null)
                throw new ConfigurationException("Configured " + configName + " \"" + intf + "\" could not be found", false);
            Enumeration<InetAddress> addrs = ni.getInetAddresses();
            if (!addrs.hasMoreElements())
                throw new ConfigurationException("Configured " + configName + " \"" + intf + "\" was found, but had no addresses", false);

            /*
             * Try to return the first address of the preferred type, otherwise return the first address
             */
            InetAddress retval = null;
            while (addrs.hasMoreElements())
            {
                InetAddress temp = addrs.nextElement();
                if (preferIPv6 && temp instanceof Inet6Address) return temp;
                if (!preferIPv6 && temp instanceof Inet4Address) return temp;
                if (retval == null) retval = temp;
            }
            return retval;
        }
        catch (SocketException e)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Run 'ip link' (Linux) or 'ifconfig -a' to list actual interface names and fix cassandra.yaml
2. Use listen_address with an explicit IP instead of listen_interface if the interface name is unstable
3. For containers/VMs, verify the interface exists inside the environment Cassandra runs in

Example fix

# before (cassandra.yaml)
listen_interface: eth1
# after
listen_interface: eth0
# or explicit address
listen_address: 10.0.0.5

boolean exists = Collections.list(NetworkInterface.getNetworkInterfaces()).stream().anyMatch(ni -> ni.getName().equals(configuredIntf)); if (!exists) throw new IllegalStateException("interface not found: " + configuredIntf);

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { log.error("startup config error: {}", e.getMessage()); System.exit(1); }

When it happens

Trigger: cassandra.yaml sets listen_interface, broadcast_interface, or rpc_interface to a name (e.g. eth1, en0) that does not exist on the machine; DatabaseDescriptor.applyAddressConfig calls this during daemon initialization.

Common situations: Copying cassandra.yaml from another machine or VM with different NIC names, container/host network interface renaming (eth0 vs ens5), or typos in the interface name.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Configured ${configName} "${intf}" was found, but had no add
• Configured ${configName} "${intf}" caused an exception
• Missing required directive CommitLogSync
• Set listen_address OR listen_interface, not both
• Invalid data storage: ${value}. It shouldn't be more than ${

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