apache/cassandra · critical · ConfigurationException

Unable to read cassandra-topology.properties

Error message

Unable to read cassandra-topology.properties

What it means

TopologyFileLocationProvider reads cassandra-topology.properties from the classpath to map node IPs to datacenter/rack locations. If the properties stream cannot be opened or loaded, loadConfiguration wraps the underlying exception in a ConfigurationException with this message, aborting node startup since location resolution is mandatory.

Solutions

  1. Place a valid cassandra-topology.properties in conf/ and ensure it is on the classpath
  2. Fix file permissions/syntax errors in the file (check the wrapped cause in the log)
  3. Set the correct config path (e.g. via cassandra-topology.properties system property / -Dcassandra.config) and restart

Example fix

// before (cassandra-topology.properties missing from conf/)
ls conf/cassandra-topology.properties -> No such file
// after
# conf/cassandra-topology.properties
192.168.0.1=dc1:rack1
192.168.0.2=dc1:rack1
Defensive patterns

Strategy: validation

Validate before calling

java.io.File f = new File("conf/cassandra-topology.properties");
if (!f.isFile() || !f.canRead()) throw new IllegalStateException("cassandra-topology.properties missing or unreadable");
try (InputStream in = new FileInputStream(f)) { new Properties().load(in); }

Try / catch

try { startNode(); }
catch (ConfigurationException e) { if (e.getMessage().contains("Unable to read cassandra-topology.properties")) { /* inspect cause, repair file/classpath, restart */ } }

Prevention

When it happens

Trigger: Starting a node with a file-based topology snitch where cassandra-topology.properties is missing from the classpath, unreadable, or malformed (properties.load throws).

Common situations: File absent in conf/ or not on the classpath; wrong file permissions; syntax errors in the properties file; running in a container where the config volume was not mounted.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

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

Appendix: source

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

        {
            return new Location(DEFAULT_DC, DEFAULT_RACK);
        }
        else
        {
            return new Location(parts[0].trim(), parts[1].trim());
        }
    }

    private Location loadConfiguration() throws ConfigurationException
    {
        Properties properties = new Properties();
        try (InputStream stream = getClass().getClassLoader().getResourceAsStream(PROPERTIES_FILENAME))
        {
            properties.load(stream);
        }
        catch (Exception e)
        {
            throw new ConfigurationException("Unable to read " + PROPERTIES_FILENAME, e);
        }

        Location local = null;
        InetAddressAndPort broadcastAddress = FBUtilities.getBroadcastAddressAndPort();
        for (Map.Entry<Object, Object> entry : properties.entrySet())
        {
            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);

View on GitHub (pinned to 88fd0f6a0e)