apache/cassandra · critical · ConfigurationException

Found system keyspace files, but they couldn't be loaded!

Error message

Found system keyspace files, but they couldn't be loaded!

What it means

During node initialization, checkHealth reads the system.local cluster_name from disk. If the query returns no cluster_name but SSTables exist for the system keyspace, the saved files could not be loaded/parsed, so Cassandra throws ConfigurationException rather than treating the node as brand new. This prevents silently re-initializing a node that already has data.

Source

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

            keyspace = Keyspace.open(SchemaConstants.SYSTEM_KEYSPACE_NAME);
        }
        catch (AssertionError err)
        {
            // this happens when a user switches from OPP to RP.
            ConfigurationException ex = new ConfigurationException("Could not read system keyspace!");
            ex.initCause(err);
            throw ex;
        }
        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));
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Confirm cassandra.yaml cluster_name and data directory correspond to the node's real data; do not point at foreign data directories
If the data is stale/unwanted, clear the system keyspace sstables (or the whole data dir) and let the node bootstrap fresh
If the data must be kept, repair the system keyspace files (restore from a full snapshot) rather than starting with a partial set
Check the logs above this error for the actual load failure (corruption, schema mismatch) and address it

Example fix

// before
start node with mixed data dirs → system sstables present but unloadable
// after
rm -rf /var/lib/cassandra/data/system/*  # only when data is intentionally discarded
start node to bootstrap fresh

Defensive patterns

Strategy: validation

Validate before calling

// before startup, verify data dir matches this node
if (hasSystemSstables(dataDir) && !cassandraYamlMatchesSavedClusterName())
    failStartup("system keyspace data present but not loadable; check data dir integrity");

Type guard

null

Try / catch

try { startCassandra(); } catch (ConfigurationException e) { if (e.getMessage().contains("couldn't be loaded")) { /* restore full snapshot or wipe data dir deliberately */ } else throw e; }

Prevention

Never share or partially copy data directories between nodes/clusters
Always restore full snapshots, never partial sstable sets
Validate data directory contents after restores before starting the node

When it happens

Trigger: Bootstrapping a node whose system keyspace sstables are unreadable/corrupt or from an incompatible schema, while cassandra.yaml lacks a matching readable cluster_name record; the local row is empty but getLiveSSTables is non-empty.

Common situations: Copying a data directory from another node/version; truncated system keyspace sstables after a crash; restoring a partial snapshot; upgrading across a major version without proper migration.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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