What causes "Error occurred during user defined compaction" in apache/cassandra?

Verify each listed SSTable file exists on the target node (files are node-local paths).

apache/cassandra · error · RuntimeException

Error occurred during user defined compaction

Error message

Error occurred during user defined compaction

What it means

When --user-defined compaction is requested, Compact calls probe.forceUserDefinedCompaction with the comma-joined SSTable file list; any Exception from the JMX call is wrapped in this RuntimeException. It indicates the node rejected or failed the user-defined compaction request.

Solutions

Verify each listed SSTable file exists on the target node (files are node-local paths).
Re-run listing only files currently present: `ls *-Data.db` / `nodetool listbackup`-style checks.
Check `nodetool compactionstats` for conflicting in-progress compactions.
Inspect the wrapped cause for the precise remote error.

Example fix

// before
nodetool compact --user-defined ks tbl data-ka-9-Data.db   # file already compacted
// after
nodetool compact --user-defined ks tbl data-ka-12-Data.db  # verify with ls first

Defensive patterns

Strategy: try-catch

Validate before calling

for (String file : args) {
    // files are node-local; verify via JMX or provisioning that each exists on the target node
    if (!file.matches(".+-Data\.db")) throw new IllegalArgumentException("Not an SSTable data file: " + file);
}

Try / catch

try { probe.forceUserDefinedCompaction(files); }
catch (RuntimeException e) {
    log("User-defined compaction failed: " + e.getCause());
    // check compactionstats and file existence before retry
}

Prevention

Verify SSTable filenames still exist right before submission (major compaction can remove them).
Run user-defined compaction per node with node-local paths.
Avoid requesting compaction of files already in an active compaction (`nodetool compactionstats`).
Use the wrapped cause to distinguish bad-file-list from transport failures.

When it happens

Trigger: Supplying file names/paths that don't exist on the node, files already being compacted, malformed file list, or a remote failure while submitting the compaction via JMX.

Common situations: Listing SSTables that were already compacted away; wrong paths on a multi-node cluster (files are node-local); node under load rejecting new compactions.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/Compact.java:88

        final boolean partitionKeyProvided = !partitionKey.isEmpty();
        final boolean tokenProvided = startEndTokenProvided || partitionKeyProvided;
        if (splitOutput && (userDefined || tokenProvided))
        {
            throw new RuntimeException("Invalid option combination: Can not use split-output here");
        }
        if (userDefined && tokenProvided)
        {
            throw new RuntimeException("Invalid option combination: Can not provide tokens when using user-defined");
        }

        if (userDefined)
        {
            try
            {
                String userDefinedFiles = String.join(",", args);
                probe.forceUserDefinedCompaction(userDefinedFiles);
            } catch (Exception e) {
                throw new RuntimeException("Error occurred during user defined compaction", e);
            }
            return;
        }

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

        for (String keyspace : keyspaces)
        {
            try
            {
                if (startEndTokenProvided)
                {
                    probe.forceKeyspaceCompactionForTokenRange(keyspace, startToken, endToken, tableNames);
                }
                else if (partitionKeyProvided)
                {
                    probe.forceKeyspaceCompactionForPartitionKey(keyspace, partitionKey, tableNames);

View on GitHub (pinned to 88fd0f6a0e)