apache/cassandra · critical · ConfigurationException

Configured ${configName} "${intf}" caused an exception

Error message

Configured ${configName} "${intf}" caused an exception

What it means

While resolving the configured interface's addresses, a java.net.SocketException was raised (e.g. I/O error querying the network stack); DatabaseDescriptor wraps it in a ConfigurationException indicating the interface caused an exception.

Source

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

            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)
        {
            throw new ConfigurationException("Configured " + configName + " \"" + intf + "\" caused an exception", e);
        }
    }

    @VisibleForTesting
    public static void setConfig(Config config)
    {
        conf = config;
    }

    private static void applyAll() throws ConfigurationException
    {
        applyCompatibilityMode();

        applySSTableFormats();

        applyCompressorProviders();

        applyCryptoProvider();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check the wrapped SocketException cause in the stack trace for the underlying OS error
2. Verify the host network stack is healthy ('ip addr', 'ip link') and restart networking if needed
3. Bypass interface resolution by using explicit listen_address/rpc_address IPs in cassandra.yaml

Example fix

# before
listen_interface: eth0
# after
listen_address: 10.0.0.5

try { NetworkInterface.getByName(intf).getInetAddresses(); } catch (SocketException e) { log.error("network stack query failed for {}: {}", intf, e); }

catch (ConfigurationException e) { if (e.getCause() instanceof SocketException) { log.error("network stack failure on {}", intf, e.getCause()); } throw e; }

When it happens

Trigger: NetworkInterface.getInetAddresses() throwing SocketException during DatabaseDescriptor initialization — caused by network stack issues, restricted /proc or namespace permissions, or unusual socket state on the host.

Common situations: Containers with restricted network namespaces, SELinux/AppArmor restrictions, or hosts with broken virtual networking (docker/veth issues) at Cassandra startup.

Related errors

• Configured ${configName} "${intf}" could not be found
• Configured ${configName} "${intf}" was found, but had no add
• Invalid data storage: ${value}. It shouldn't be more than ${
• Invalid data storage: value must be non-negative
• Invalid data storage: %d %s. It shouldn't be more than %d in

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