apache/cassandra · critical · ConfigurationException

Set listen_address OR listen_interface, not both

Error message

Set listen_address OR listen_interface, not both

What it means

DatabaseDescriptor.applyAddressConfig validates the network binding configuration. Cassandra binds its internal server to either listen_address (an IP/hostname) or listen_interface (a NIC name) — never both. When both keys are non-null in cassandra.yaml, the node refuses to start with this ConfigurationException.

Source

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

        }
    }

    public static void applyAddressConfig() throws ConfigurationException
    {
        applyAddressConfig(conf);
    }

    public static void applyAddressConfig(Config config) throws ConfigurationException
    {
        listenAddress = null;
        rpcAddress = null;
        broadcastAddress = null;
        broadcastRpcAddress = null;

        /* Local IP, hostname or interface to bind services to */
        if (config.listen_address != null && config.listen_interface != null)
        {
            throw new ConfigurationException("Set listen_address OR listen_interface, not both", false);
        }
        else if (config.listen_address != null)
        {
            try
            {
                listenAddress = InetAddress.getByName(config.listen_address);
            }
            catch (UnknownHostException e)
            {
                throw new ConfigurationException("Unknown listen_address '" + config.listen_address + '\'', false);
            }

            if (listenAddress.isAnyLocalAddress())
                throw new ConfigurationException("listen_address cannot be a wildcard address (" + config.listen_address + ")!", false);
        }
        else if (config.listen_interface != null)
        {
            listenAddress = getNetworkInterfaceAddress(config.listen_interface, "listen_interface", config.listen_interface_prefer_ipv6);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Open cassandra.yaml and keep exactly one of listen_address or listen_interface (comment the other out).
2. Most installations should set listen_address to the node IP and leave listen_interface commented.
3. Restart Cassandra after the edit.

Example fix

# before (cassandra.yaml)
listen_address: 10.0.0.5
listen_interface: eth0
# after
listen_address: 10.0.0.5
# listen_interface: eth0

yaml = YAML.load(File.read('conf/cassandra.yaml'))
raise 'Set listen_address OR listen_interface, not both' if yaml['listen_address'] && yaml['listen_interface']

catch (ConfigurationException e) { logger.error("cassandra.yaml address conflict: {}", e.getMessage()); System.exit(2); }

When it happens

Trigger: cassandra.yaml has non-null values for both listen_address and listen_interface at the same time.

Common situations: uncommenting listen_interface while forgetting to comment out the default listen_address: localhost line; templating tools (Chef/Puppet/Ansible) that append both settings; merging cluster configs.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Configured ${configName} "${intf}" could not be found
• Configured ${configName} "${intf}" was found, but had no add
• memtable_cleanup_threshold must be >= 0.01, but was ${conf.m
• memtable_cleanup_threshold must be <= 0.99, but was ${conf.m
• native_transport_max_message_size must not exceed native_tra

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