{"record":{"id":"8488ff988109efc1","repo":"apache/cassandra","slug":"cleanup-of-the-system-keyspace-is-neither-necessar","errorCode":null,"errorMessage":"Cleanup of the system keyspace is neither necessary nor wise","messagePattern":"Cleanup of the system keyspace is neither necessary nor wise","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/service/StorageService.java","lineNumber":2712,"sourceCode":"    public String getSavedCachesLocation()\n    {\n        return FileUtils.getCanonicalPath(DatabaseDescriptor.getSavedCachesLocation());\n    }\n\n    public int getCurrentGenerationNumber()\n    {\n        return Gossiper.instance.getCurrentGenerationNumber(getBroadcastAddressAndPort());\n    }\n\n    public int forceKeyspaceCleanup(String keyspaceName, String... tables) throws IOException, ExecutionException, InterruptedException\n    {\n        return forceKeyspaceCleanup(0, keyspaceName, tables);\n    }\n\n    public int forceKeyspaceCleanup(int jobs, String keyspaceName, String... tableNames) throws IOException, ExecutionException, InterruptedException\n    {\n        if (isLocalSystemKeyspace(keyspaceName))\n            throw new RuntimeException(\"Cleanup of the system keyspace is neither necessary nor wise\");\n\n        CompactionManager.AllSSTableOpStatus status = CompactionManager.AllSSTableOpStatus.SUCCESSFUL;\n        logger.info(\"Starting {} on {}.{}\", OperationType.CLEANUP, keyspaceName, Arrays.toString(tableNames));\n        for (ColumnFamilyStore cfStore : getValidColumnFamilies(false, false, keyspaceName, tableNames))\n        {\n            CompactionManager.AllSSTableOpStatus oneStatus = cfStore.forceCleanup(jobs);\n            if (oneStatus != CompactionManager.AllSSTableOpStatus.SUCCESSFUL)\n                status = oneStatus;\n        }\n        logger.info(\"Completed {} with status {}\", OperationType.CLEANUP, status);\n        return status.statusCode;\n    }\n\n    public int scrub(boolean disableSnapshot, boolean skipCorrupted, boolean checkData, boolean reinsertOverflowedTTL, int jobs, String keyspaceName, String... tableNames) throws IOException, ExecutionException, InterruptedException\n    {\n        IScrubber.Options options = IScrubber.options()\n                                             .skipCorrupted(skipCorrupted)\n                                             .checkData(checkData)","sourceCodeStart":2694,"sourceCodeEnd":2730,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StorageService.java#L2694-L2730","documentation":"forceKeyspaceCleanup on the system keyspace is rejected because the system keyspace's data must never be compacted away — cleanup removes data not owned by this node, and system tables (auth, local, peers, etc.) are always locally owned and required for operation. Thrown as RuntimeException to make the misuse obvious.","triggerScenarios":"Running `nodetool cleanup` against the 'system' keyspace, or calling StorageServiceMBean.forceKeyspaceCleanup / forceKeyspaceCleanup(int, String, String...) with keyspaceName='system'.","commonSituations":"Operators running cleanup across all keyspaces by scripting per-keyspace calls without excluding 'system'; confusion between 'system' and 'system_auth'/'system_distributed' (the latter are cleanable).","solutions":["Exclude the 'system' keyspace from your cleanup loop or command","Only run cleanup on user keyspaces and system_auth/system_distributed/system_traces if needed","If disk space in system tables is the concern, investigate table-specific issues instead of cleanup"],"exampleFix":"// before\nfor (String ks : keyspaces) storageService.forceKeyspaceCleanup(0, ks);\n// after\nfor (String ks : keyspaces)\n    if (!ks.equals(\"system\")) storageService.forceKeyspaceCleanup(0, ks);","handlingStrategy":"validation","validationCode":"if (keyspace.equals(\"system\"))\n    skipCleanup(keyspace); // never cleanup the system keyspace","typeGuard":null,"tryCatchPattern":"try { ss.forceKeyspaceCleanup(0, ks); } catch (RuntimeException e) { log.warn(\"skipped {}: {}\", ks, e.getMessage()); }","preventionTips":["Maintain an explicit allowlist of user keyspaces for maintenance jobs","Never iterate 'all keyspaces' blindly in cleanup scripts","Remember system_auth/system_distributed/system_traces are cleanable but 'system' is not"],"tags":["cassandra","nodetool","maintenance","system-keyspace"],"backgroundTag":"invalid-argument-value","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"}