apache/cassandra · error · ConfigurationException

Unknown host

Error message

Unknown host 

What it means

TopologyFileLocationProvider loads a topology properties file mapping node IPs/broadcast addresses to rack/datacenter Locations. During loadConfiguration, each value is resolved via makeLocation which calls InetAddress.getByName; an UnknownHostException means a host string in the file could not be resolved, so the snitch configuration cannot be built and a ConfigurationException is thrown wrapping the original error.

Source

Thrown at src/java/org/apache/cassandra/locator/TopologyFileLocationProvider.java:128

        {
            String key = (String) entry.getKey();
            String value = (String) entry.getValue();
            if (DEFAULT_PROPERTY.equals(key))
                continue;

            String hostString = StringUtils.remove(key, '/');
            try
            {
                InetAddressAndPort host = InetAddressAndPort.getByName(hostString);
                if (host.equals(broadcastAddress))
                {
                    local = makeLocation(value);
                    break;
                }
            }
            catch (UnknownHostException e)
            {
                throw new ConfigurationException("Unknown host " + hostString, e);
            }

        }

        // This may be null, which is ok unless config doesn't contain the location of the local node
        Location defaultLocation = makeLocation(properties.getProperty(DEFAULT_PROPERTY));

        if (local == null)
        {
            if (defaultLocation == null)
            {
                throw new ConfigurationException(String.format("Snitch definitions at %s do not define a location for " +
                                                               "this node's broadcast address %s, nor does it provides a default",
                                                               PROPERTIES_FILENAME, broadcastAddress));
            }
            else
            {
                logger.debug("Broadcast address {} was not present in snitch config, using default location {}. " +

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Replace the unresolvable hostname in cassandra-topology.properties with the node's IP address or a resolvable DNS name
2. Verify DNS resolution from the Cassandra node (e.g. `getent hosts <name>` or `nslookup`)
3. Remove stale entries for decommissioned nodes from the properties file
4. Ensure the DEFAULT_PROPERTY (default location) value also resolves correctly

Example fix

# before (cassandra-topology.properties)
10.0.0.5=node1.internal.old-dns.zone:RAC1

# after
10.0.0.5=10.0.0.5:RAC1

for (String host : hostsInTopologyFile) {
    try { InetAddress.getByName(host); }
    catch (UnknownHostException e) { throw new IllegalArgumentException("Unresolvable host in topology file: " + host, e); }
}

try { startCassandra(); } catch (ConfigurationException e) { logger.error("Topology config invalid: {}", e.getMessage()); }

When it happens

Trigger: The topology.properties file (cassandra-topology.properties) contains an unresolvable hostname or malformed IP in a node mapping (or the default) value, so InetAddress.getByName fails while building the Location for that entry.

Common situations: Typos in hostnames in cassandra-topology.properties; DNS not resolvable in the cluster environment (private IPs or no reverse DNS); stale entries for decommissioned nodes; using hostnames in containers/Kubernetes where DNS names change.

Related errors

• Unknown listen_address '
• Unknown broadcast_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/13607ea9437cea2b. Report an issue: GitHub.