apache/cassandra · critical · ConfigurationException

listen_address cannot be a wildcard address (

Error message

listen_address cannot be a wildcard address (

What it means

After successfully resolving listen_address, Cassandra rejects wildcard (0.0.0.0 / ::) values. A node's listen address must be a specific interface address so gossip can identify it; binding to all interfaces is not a valid node identity and throws this ConfigurationException.

Source

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

        /* 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);
        }

        /* Gossip Address to broadcast */
        if (config.broadcast_address != null)
        {
            try
            {
                broadcastAddress = InetAddress.getByName(config.broadcast_address);
            }
            catch (UnknownHostException e)
            {
                throw new ConfigurationException("Unknown broadcast_address '" + config.broadcast_address + '\'', false);
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set listen_address to the node's specific IP (e.g. 10.0.0.5) in cassandra.yaml.
2. Use listen_interface: eth0 instead if you want automatic interface detection.
3. Remember 0.0.0.0 is only valid for rpc_address/broadcast settings semantics, never listen_address or broadcast_address.

Example fix

# before (cassandra.yaml)
listen_address: 0.0.0.0
# after
listen_address: 10.0.0.5

addr = yaml['listen_address']
raise 'listen_address cannot be a wildcard address' if %w[0.0.0.0 ::].include?(addr)

catch (ConfigurationException e) { logger.error("listen_address is wildcard: {}", e.getMessage()); System.exit(2); }

When it happens

Trigger: config.listen_address resolves to InetAddress.isAnyLocalAddress() == true, e.g. listen_address: 0.0.0.0 or :: in cassandra.yaml.

Common situations: Copying rpc_address: 0.0.0.0 style configs into listen_address; misunderstanding that 0.0.0.0 is only acceptable for rpc_address; cloud templates that default listen_address to 0.0.0.0.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• broadcast_address cannot be a wildcard address (
• Set listen_address OR listen_interface, not both
• Unknown listen_address '
• Unknown broadcast_address '
• Set rpc_address OR rpc_interface, not both

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