apache/cassandra · critical · ConfigurationException

Saved cluster name <savedClusterName> != configured name <co

Error message

Saved cluster name <savedClusterName> != configured name <configuredClusterName>

What it means

checkHealth compares the cluster_name persisted in system.local with the cluster_name configured in cassandra.yaml. Any mismatch throws ConfigurationException, because a node joining with the wrong cluster name would corrupt cluster membership and gossip. This is an intentional safety check at startup.

Source

Thrown at src/java/org/apache/cassandra/db/SystemKeyspace.java:1232

        }
        ColumnFamilyStore cfs = keyspace.getColumnFamilyStore(LOCAL);

        String req = "SELECT cluster_name FROM system.%s WHERE key='%s'";
        UntypedResultSet result = executeInternal(format(req, LOCAL, LOCAL));

        if (result.isEmpty() || !result.one().has("cluster_name"))
        {
            // this is a brand new node
            if (!cfs.getLiveSSTables().isEmpty())
                throw new ConfigurationException("Found system keyspace files, but they couldn't be loaded!");

            // no system files.  this is a new node.
            return;
        }

        String savedClusterName = result.one().getString("cluster_name");
        if (!DatabaseDescriptor.getClusterName().equals(savedClusterName))
            throw new ConfigurationException("Saved cluster name " + savedClusterName + " != configured name " + DatabaseDescriptor.getClusterName());
    }

    public static Collection<Token> getSavedTokens()
    {
        String req = "SELECT tokens FROM system.%s WHERE key='%s'";
        UntypedResultSet result = executeInternal(format(req, LOCAL, LOCAL));
        return result.isEmpty() || !result.one().has("tokens")
             ? Collections.<Token>emptyList()
             : deserializeTokens(result.one().getSet("tokens", UTF8Type.instance));
    }

    public static int incrementAndGetGeneration()
    {
        String req = "SELECT gossip_generation FROM system.%s WHERE key='%s'";
        UntypedResultSet result = executeInternal(format(req, LOCAL, LOCAL));

        int generation;
        if (result.isEmpty() || !result.one().has("gossip_generation"))

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Restore cassandra.yaml cluster_name to the saved value shown in the error message and restart
2. If renaming is truly intended, wipe the data directory and re-bootstrap the node into the new cluster
3. Verify data_dir points to this cluster's data, not a copied directory from another environment
4. Check the saved name with cqlsh: SELECT cluster_name FROM system.local;

Example fix

// before (cassandra.yaml)
cluster_name: 'Prod Cluster'
// after (match saved name)
cluster_name: 'Staging Cluster'

String saved = savedClusterNameFromSystemLocal(); // e.g. via cqlsh or sstable metadata
if (saved != null && !saved.equals(yamlClusterName))
    throw new IllegalStateException("cluster_name mismatch: yaml=" + yamlClusterName + " saved=" + saved);

null

try { startCassandra(); } catch (ConfigurationException e) { if (e.getMessage().contains("Saved cluster name")) { /* align cassandra.yaml or re-bootstrap */ } else throw e; }

When it happens

Trigger: Starting a node whose system.local row stores a saved cluster name different from DatabaseDescriptor.getClusterName(), typically after editing cluster_name in cassandra.yaml on an existing node, or pointing the data directory at data from another cluster.

Common situations: Renaming a cluster by editing yaml instead of doing a clean re-bootstrap; copying data directories between clusters/environments (staging vs prod); misconfigured dc rollout reusing another cluster's data disk.

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

• %s has authorization enabled which requires %s to enable aut
• %s requires %s
• %s can't be used with %s
• %s does not support %s
• Failed to instantiate %s

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