{"record":{"id":"209a9c631fea82a1","repo":"apache/cassandra","slug":"error-occurred-during-user-defined-garbage-collect","errorCode":null,"errorMessage":"Error occurred during user defined garbage collection","messagePattern":"Error occurred during user defined garbage collection","errorType":"console","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/tools/nodetool/GarbageCollect.java","lineNumber":80,"sourceCode":"    @Option(names = { \"--user-defined\" },\n            description = \"Submit the listed Data.db files for user-defined garbagecollect instead of \" +\n                          \"interpreting the positional arguments as keyspace + tables.\")\n    private boolean userDefined = false;\n\n    @Override\n    public void execute(NodeProbe probe)\n    {\n        args = concatArgs(keyspace, tables);\n\n        if (userDefined)\n        {\n            try\n            {\n                probe.userDefinedGarbageCollect(probe.output().out, tombstoneOption.toString(), jobs, args);\n            }\n            catch (Exception e)\n            {\n                throw new RuntimeException(\"Error occurred during user defined garbage collection\", e);\n            }\n            return;\n        }\n\n        List<String> keyspaces = parseOptionalKeyspace(args, probe);\n        String[] tableNames = parseOptionalTables(args);\n\n        for (String keyspace : keyspaces)\n        {\n            try\n            {\n                probe.garbageCollect(probe.output().out, tombstoneOption.toString(), jobs, keyspace, tableNames);\n            } catch (Exception e)\n            {\n                throw new RuntimeException(\"Error occurred during garbage collection\", e);\n            }\n        }\n    }","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/tools/nodetool/GarbageCollect.java#L62-L98","documentation":"GarbageCollect, when run on all keyspaces (no keyspace arguments), wraps any exception from userDefinedGarbageCollect in a RuntimeException. It indicates the server-side user-defined tombstone GC (compaction) operation failed on at least one target or the JMX call failed.","triggerScenarios":"Running `nodetool garbagecollect` without keyspace args with an invalid tombstone option (-t/--tomstone-option value other than row|cell), bad -j jobs value, or a server-side compaction failure while iterating all keyspaces.","commonSituations":"Tombstone purge maintenance on clusters with many keyspaces; operator passes an unsupported tombstone option; node under heavy compaction load rejects the request.","solutions":["Check the 'Caused by' exception for the true failure reason","Verify --tomstone-option is 'row' or 'cell' and -j is a valid job count (0-16)","Run garbagecollect against one keyspace/table at a time to isolate the failing target","Retry during lower compaction load"],"exampleFix":"// before\nnodetool garbagecollect --tomstone-option cell -j 100\n// after\nnodetool garbagecollect --tomstone-option cell -j 2","handlingStrategy":"validation","validationCode":"[ \"$TOMBSTONE_OPTION\" = \"row\" ] || [ \"$TOMBSTONE_OPTION\" = \"cell\" ] || { echo 'bad --tomstone-option'; exit 1; }\n[ \"$JOBS\" -ge 0 ] && [ \"$JOBS\" -le 16 ] || { echo 'bad -j'; exit 1; }","typeGuard":null,"tryCatchPattern":"try { probe.userDefinedGarbageCollect(out, opt, jobs, args); } catch (RuntimeException e) { handle(e.getCause()); }","preventionTips":["Validate tombstone option and job count in wrapper scripts","Target specific keyspaces first to isolate failures","Avoid running GC compaction during repair or heavy compaction"],"tags":["nodetool","jmx","garbage-collect"],"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-17T15:17:12.973Z"}