apache/cassandra · error · ConfigurationException

Snitch definitions at %s do not define a location for this n

Error message

Snitch definitions at %s do not define a location for this node's broadcast address %s, nor does it provides a default

What it means

TopologyFileLocationProvider requires that the loaded topology properties file either contain an entry for this node's broadcast address or define a default location. If the local node's address is absent from the file and no default is configured, a ConfigurationException is thrown because the snitch cannot determine the node's datacenter/rack.

Source

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

                    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 {}. " +
                             "This only matters on first boot, before registering with the cluster metadata service",
                             broadcastAddress, defaultLocation);
                local = defaultLocation;
            }
        }

        logger.debug("Loaded location {} for broadcast address {} from property file. " +
                     "This only matters on first boot, before registering with the cluster metadata service",
                     local, broadcastAddress);

        return local;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Add an entry for this node's broadcast address to cassandra-topology.properties mapping it to dc:rack
Add a `default=<dc>:<rack>` line to cassandra-topology.properties as a fallback
Verify the value of broadcast_address in cassandra.yaml matches an existing key in the properties file
Restart the node after fixing the properties file

Example fix

# before (cassandra-topology.properties missing the node)
10.0.0.5=DC1:RAC1

# after
10.0.0.5=DC1:RAC1
10.0.0.9=DC1:RAC2
default=DC1:RAC1

Defensive patterns

Strategy: validation

Validate before calling

Properties p = new Properties();
p.load(new FileInputStream(confDir + "/cassandra-topology.properties"));
String broadcast = getBroadcastAddress().getHostAddress();
if (!p.containsKey(broadcast) && !p.containsKey("default"))
    throw new IllegalArgumentException("Topology file missing entry for " + broadcast + " and no default");

Try / catch

try { startCassandra(); } catch (ConfigurationException e) { logger.error("Node location undefined in topology file: {}", e.getMessage()); }

Prevention

Always define a `default` location line in cassandra-topology.properties
Keep broadcast_address consistent with the keys in the topology file
Update the topology file whenever adding nodes or changing IPs

When it happens

Trigger: Node starts with a broadcast_address (or broadcast_address set via config) that has no key in cassandra-topology.properties, and the file has no `default` property defined.

Common situations: Node's IP changed after adding it to the cluster; broadcast_address configured differently from the address listed in the properties file; new node added without updating the topology file; missing `default` line in the properties file.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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