apache/cassandra · critical · ConfigurationException

Unknown broadcast_rpc_address '

Error message

Unknown broadcast_rpc_address '

What it means

DatabaseDescriptor.applySimpleConfig / applyAddressConfig validates the cassandra.yaml broadcast_rpc_address setting by resolving it with InetAddress.getByName. If the hostname cannot be resolved via DNS, an UnknownHostException is wrapped in a ConfigurationException and startup aborts because the node cannot advertise an unreachable RPC address to clients.

Source

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

        else if (config.rpc_interface != null)
        {
            rpcAddress = getNetworkInterfaceAddress(config.rpc_interface, "rpc_interface", config.rpc_interface_prefer_ipv6);
        }
        else
        {
            rpcAddress = FBUtilities.getJustLocalAddress();
        }

        /* RPC address to broadcast */
        if (config.broadcast_rpc_address != null)
        {
            try
            {
                broadcastRpcAddress = InetAddress.getByName(config.broadcast_rpc_address);
            }
            catch (UnknownHostException e)
            {
                throw new ConfigurationException("Unknown broadcast_rpc_address '" + config.broadcast_rpc_address + '\'', false);
            }

            if (broadcastRpcAddress.isAnyLocalAddress())
                throw new ConfigurationException("broadcast_rpc_address cannot be a wildcard address (" + config.broadcast_rpc_address + ")!", false);
        }
        else
        {
            if (rpcAddress.isAnyLocalAddress())
                throw new ConfigurationException("If rpc_address is set to a wildcard address (" + config.rpc_address + "), then " +
                                                 "you must set broadcast_rpc_address to a value other than " + config.rpc_address, false);
        }
    }

    public static void applyEncryptionContext()
    {
        // always attempt to load the cipher factory, as we could be in the situation where the user has disabled encryption,
        // but has existing commitlogs and sstables on disk that are still encrypted (and still need to be read)
        encryptionContext = new EncryptionContext(conf.transparent_data_encryption_options);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Fix broadcast_rpc_address in cassandra.yaml to a resolvable hostname or, simplest, an explicit IP address
  2. Add the hostname to /etc/hosts or fix DNS so it resolves before Cassandra starts
  3. If the setting is unnecessary (no NAT/overlay), remove or comment out broadcast_rpc_address so the RPC address is derived from rpc_address
  4. Verify with `getent hosts <name>` (or `nslookup`) before starting Cassandra

Example fix

// cassandra.yaml before
broadcast_rpc_address: rpc-node-01.internal.example
// after (use resolvable name or literal IP)
broadcast_rpc_address: 10.0.1.5
Defensive patterns

Strategy: validation

Validate before calling

String addr = config.broadcast_rpc_address;
if (addr != null) {
    try { java.net.InetAddress.getByName(addr); }
    catch (java.net.UnknownHostException e) { throw new IllegalStateException("broadcast_rpc_address unresolvable: " + addr); }
}

Try / catch

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { logger.error("Config error: {}", e.getMessage()); System.exit(1); }

Prevention

When it happens

Trigger: Calling DatabaseDescriptor.loadConfig()/applyAddressConfig() (e.g. during daemon startup) when config.broadcast_rpc_address is set to a hostname that DNS cannot resolve — typo, stale entry, or nameserver outage.

Common situations: cassandra.yaml edited by hand with a misspelled hostname; /etc/hosts entry removed; DNS not yet up at node boot in containers; using a public DNS name in an air-gapped cluster.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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