apache/cassandra · critical · ConfigurationException

Unknown host in rpc_address

Error message

Unknown host in rpc_address 

What it means

The rpc_address value in cassandra.yaml could not be resolved to an IP address: InetAddress.getByName() threw UnknownHostException, which DatabaseDescriptor wraps into this ConfigurationException. The native transport server cannot determine its bind address, so startup aborts.

Source

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

            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)
            {
                throw new ConfigurationException("Unknown host in rpc_address " + config.rpc_address, false);
            }
        }
        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);
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Replace the hostname in rpc_address with the node's raw IP address.
2. Or fix host resolution (add the name to /etc/hosts / correct DNS).
3. Check the echoed value in the error message for typos.

Example fix

# before (cassandra.yaml)
rpc_address: cassandra-5
# after
rpc_address: 10.0.0.5

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

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

When it happens

Trigger: config.rpc_address is non-null and InetAddress.getByName(config.rpc_address) throws UnknownHostException.

Common situations: Setting rpc_address to a hostname absent from /etc/hosts (default template uses hostname resolution); typos; containers started before network/DNS is ready; renamed hosts with stale DNS.

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 '
• Unknown broadcast_address '
• Set rpc_address OR rpc_interface, not both
• 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/a67834ef6cc502e1. Report an issue: GitHub.