{"record":{"id":"41d3aae2384d3c9e","repo":"apache/cassandra","slug":"found-system-keyspace-files-but-they-couldn-t-be","errorCode":null,"errorMessage":"Found system keyspace files, but they couldn't be loaded!","messagePattern":"Found system keyspace files, but they couldn't be loaded!","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/db/SystemKeyspace.java","lineNumber":1224,"sourceCode":"            keyspace = Keyspace.open(SchemaConstants.SYSTEM_KEYSPACE_NAME);\n        }\n        catch (AssertionError err)\n        {\n            // this happens when a user switches from OPP to RP.\n            ConfigurationException ex = new ConfigurationException(\"Could not read system keyspace!\");\n            ex.initCause(err);\n            throw ex;\n        }\n        ColumnFamilyStore cfs = keyspace.getColumnFamilyStore(LOCAL);\n\n        String req = \"SELECT cluster_name FROM system.%s WHERE key='%s'\";\n        UntypedResultSet result = executeInternal(format(req, LOCAL, LOCAL));\n\n        if (result.isEmpty() || !result.one().has(\"cluster_name\"))\n        {\n            // this is a brand new node\n            if (!cfs.getLiveSSTables().isEmpty())\n                throw new ConfigurationException(\"Found system keyspace files, but they couldn't be loaded!\");\n\n            // no system files.  this is a new node.\n            return;\n        }\n\n        String savedClusterName = result.one().getString(\"cluster_name\");\n        if (!DatabaseDescriptor.getClusterName().equals(savedClusterName))\n            throw new ConfigurationException(\"Saved cluster name \" + savedClusterName + \" != configured name \" + DatabaseDescriptor.getClusterName());\n    }\n\n    public static Collection<Token> getSavedTokens()\n    {\n        String req = \"SELECT tokens FROM system.%s WHERE key='%s'\";\n        UntypedResultSet result = executeInternal(format(req, LOCAL, LOCAL));\n        return result.isEmpty() || !result.one().has(\"tokens\")\n             ? Collections.<Token>emptyList()\n             : deserializeTokens(result.one().getSet(\"tokens\", UTF8Type.instance));\n    }","sourceCodeStart":1206,"sourceCodeEnd":1242,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/SystemKeyspace.java#L1206-L1242","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nstart node with mixed data dirs → system sstables present but unloadable\n// after\nrm -rf /var/lib/cassandra/data/system/*  # only when data is intentionally discarded\nstart node to bootstrap fresh","handlingStrategy":"validation","validationCode":"// before startup, verify data dir matches this node\nif (hasSystemSstables(dataDir) && !cassandraYamlMatchesSavedClusterName())\n    failStartup(\"system keyspace data present but not loadable; check data dir integrity\");","typeGuard":"null","tryCatchPattern":"try { startCassandra(); } catch (ConfigurationException e) { if (e.getMessage().contains(\"couldn't be loaded\")) { /* restore full snapshot or wipe data dir deliberately */ } else throw e; }","preventionTips":["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"],"tags":["startup","system-keyspace","configuration","corruption"],"backgroundTag":"invalid-state-transition","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}