apache/cassandra · error · java.lang.IllegalArgumentException

argument for sort must be one of

Error message

argument for sort must be one of: %s

What it means

TableStats supports sorting output via a sort key, validated against StatsTableComparator.supportedSortKeys. Passing a key outside that allowlist throws IllegalArgumentException listing the valid keys. This prevents silent no-op sorts on misspelled column names.

Solutions

  1. Read the error message, which enumerates the valid keys, and use one of them verbatim.
  2. Check StatsTableComparator.supportedSortKeys in the source for the exact names in your Cassandra version.
  3. Upgrade/downgrade scripts to match the key names of the deployed Cassandra version.

Example fix

// before
nodetool tablestats -s write_latency --top 5
// after
nodetool tablestats -s write_latency_ms --top 5  // use a key from supportedSortKeys
Defensive patterns

Strategy: validation

Validate before calling

// read valid keys from the error output once and hardcode the allowlist
java.util.Set<String> valid = java.util.Set.of("write_latency_ms", "read_latency_ms", "sstables_per_read", "space_used_live");
if (!valid.contains(sortKey)) throw new IllegalArgumentException("bad sort key: " + sortKey);

Try / catch

try { runNodetool("tablestats", "-s", key); }
catch (IllegalArgumentException e) { if (e.getMessage().contains("argument for sort")) { /* parse valid keys from message and retry */ } else throw e; }

Prevention

When it happens

Trigger: `nodetool tablestats -s <wrongKey>` where the key is not in supportedSortKeys (e.g. 'write_latency' instead of the exact supported name like 'write_latency_ms' or whatever the build's list contains).

Common situations: Guessing sort-key names instead of copying from the error message; scripts written against an older Cassandra version whose supported key list changed; mixing up space- vs underscore-separated names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/TableStats.java:96

            description = "Show only the top K tables for the sort key (specify the number K of tables to be shown")
    private int top = 0;

    @Option(paramLabel = "sstable_location_check",
            names = { "-l", "--sstable-location-check" },
            description = "Check whether or not the SSTables are in the correct location.")
    private boolean locationCheck = false;

    @Override
    public void execute(NodeProbe probe)
    {
        if (!outputFormat.isEmpty() && !"json".equals(outputFormat) && !"yaml".equals(outputFormat))
        {
            throw new IllegalArgumentException("arguments for -F are json,yaml only.");
        }

        if (!sortKey.isEmpty() && !Arrays.asList(StatsTableComparator.supportedSortKeys).contains(sortKey))
        {
            throw new IllegalArgumentException(String.format("argument for sort must be one of: %s",
                                               String.join(", ", StatsTableComparator.supportedSortKeys)));
        }

        if (top > 0 && sortKey.isEmpty())
        {
            throw new IllegalArgumentException("cannot filter top K tables without specifying a sort key.");
        }

        if (top < 0)
        {
            throw new IllegalArgumentException("argument for top must be a positive integer.");
        }

        StatsHolder holder = new TableStatsHolder(probe, humanReadable, ignore, tableNames, sortKey, top, locationCheck);
        // print out the keyspace and table statistics
        StatsPrinter printer = TableStatsPrinter.from(outputFormat, !sortKey.isEmpty());
        printer.print(holder, probe.output().out);
    }

View on GitHub (pinned to 88fd0f6a0e)