apache/cassandra · critical · ConfigurationException

Unknown listen_address '

Error message

Unknown listen_address '

What it means

Cassandra tried to resolve the listen_address value from cassandra.yaml to an IP with InetAddress.getByName() and got an UnknownHostException. The configured hostname cannot be resolved via DNS or /etc/hosts, so the node cannot bind and throws this ConfigurationException (before the related wildcard-address check).

Source

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

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

        /* Gossip Address to broadcast */
        if (config.broadcast_address != null)
        {
            try
            {
                broadcastAddress = InetAddress.getByName(config.broadcast_address);
            }
            catch (UnknownHostException e)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use the node's raw IP address for listen_address in cassandra.yaml instead of a hostname.
2. If keeping a hostname, add a /etc/hosts entry or fix DNS so it resolves from the node.
3. Check for typos in the listen_address value (the message echoes it).

Example fix

# before (cassandra.yaml)
listen_address: node5.internal.example
# after (hosts unresolvable)
listen_address: 10.0.0.5

addr = yaml['listen_address']
raise "listen_address '#{addr}' unresolvable" if addr && !addr.match?(Resolv::IPv4::Regex) && !Resolv.getaddress(addr)

catch (ConfigurationException e) { logger.error("listen_address does not resolve: {}", e.getMessage()); System.exit(2); }

When it happens

Trigger: config.listen_address is set to a hostname that InetAddress.getByName() cannot resolve (UnknownHostException).

Common situations: Using a hostname not present in /etc/hosts or DNS; typo in the hostname; DNS resolver broken in the container; using the FQDN before network is up during early boot.

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

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

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