apache/cassandra · critical · ConfigurationException

Unknown broadcast_address '

Error message

Unknown broadcast_address '

What it means

The broadcast_address value in cassandra.yaml could not be resolved to an IP: InetAddress.getByName() threw UnknownHostException and DatabaseDescriptor converted it into this ConfigurationException. broadcast_address is what other nodes see, so it must resolve to the node's routable address.

Source

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

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

            if (broadcastAddress.isAnyLocalAddress())
                throw new ConfigurationException("broadcast_address cannot be a wildcard address (" + config.broadcast_address + ")!", false);
        }

        /* Local IP, hostname or interface to bind RPC server to */
        if (config.rpc_address != null && config.rpc_interface != null)
        {
            throw new ConfigurationException("Set rpc_address OR rpc_interface, not both", false);
        }
        else if (config.rpc_address != null)
        {
            try
            {
                rpcAddress = InetAddress.getByName(config.rpc_address);
            }
            catch (UnknownHostException e)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set broadcast_address to an IP address that resolves from the node (or remove broadcast_address if it equals listen_address).
2. Fix /etc/hosts or DNS so the configured hostname resolves.
3. Verify the value matches the address peers should use to reach this node.

Example fix

# before (cassandra.yaml)
broadcast_address: cassandra-node5.public.example
# after
broadcast_address: 10.0.0.5

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

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

When it happens

Trigger: config.broadcast_address is set and InetAddress.getByName(config.broadcast_address) fails with UnknownHostException.

Common situations: Setting broadcast_address to an external/public hostname that does not resolve from inside the node (common in NAT/cloud multi-DC setups); typo in the hostname; stale DNS after instance rename.

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 listen_address '
• broadcast_address cannot be a wildcard address (
• Unknown host in rpc_address
• Set listen_address OR listen_interface, not both
• listen_address cannot be a wildcard address (

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