apache/cassandra · error · RuntimeException

Error occurred during user defined garbage collection

Error message

Error occurred during user defined garbage collection

What it means

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.

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

Example fix

// before
nodetool garbagecollect --tomstone-option cell -j 100
// after
nodetool garbagecollect --tomstone-option cell -j 2

Defensive patterns

Strategy: validation

Validate before calling

[ "$TOMBSTONE_OPTION" = "row" ] || [ "$TOMBSTONE_OPTION" = "cell" ] || { echo 'bad --tomstone-option'; exit 1; }
[ "$JOBS" -ge 0 ] && [ "$JOBS" -le 16 ] || { echo 'bad -j'; exit 1; }

Try / catch

try { probe.userDefinedGarbageCollect(out, opt, jobs, args); } catch (RuntimeException e) { handle(e.getCause()); }

Prevention

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

When it happens

Trigger: 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.

Common situations: Tombstone purge maintenance on clusters with many keyspaces; operator passes an unsupported tombstone option; node under heavy compaction load rejects the request.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/GarbageCollect.java:80

    @Option(names = { "--user-defined" },
            description = "Submit the listed Data.db files for user-defined garbagecollect instead of " +
                          "interpreting the positional arguments as keyspace + tables.")
    private boolean userDefined = false;

    @Override
    public void execute(NodeProbe probe)
    {
        args = concatArgs(keyspace, tables);

        if (userDefined)
        {
            try
            {
                probe.userDefinedGarbageCollect(probe.output().out, tombstoneOption.toString(), jobs, args);
            }
            catch (Exception e)
            {
                throw new RuntimeException("Error occurred during user defined garbage collection", e);
            }
            return;
        }

        List<String> keyspaces = parseOptionalKeyspace(args, probe);
        String[] tableNames = parseOptionalTables(args);

        for (String keyspace : keyspaces)
        {
            try
            {
                probe.garbageCollect(probe.output().out, tombstoneOption.toString(), jobs, keyspace, tableNames);
            } catch (Exception e)
            {
                throw new RuntimeException("Error occurred during garbage collection", e);
            }
        }
    }

View on GitHub (pinned to 88fd0f6a0e)