apache/cassandra · error · java.lang.IllegalArgumentException

cannot filter top K tables without specifying a sort key.

Error message

cannot filter top K tables without specifying a sort key.

What it means

The --top N option of TableStats only makes sense together with a sort key, because 'top K' is defined by a sort order. If -t/--top is given a positive value while no sort key was supplied, execute() throws IllegalArgumentException. The ordering is what makes 'top' meaningful.

Solutions

1. Add a valid -s/--sort-key alongside --top (e.g. `nodetool tablestats -s read_latency_ms --top 5`).
2. Remove --top if you want the full unsorted listing.
3. Consult `nodetool help tablestats` for the exact flag pairing.

Example fix

// before
nodetool tablestats --top 5
// after
nodetool tablestats -s read_latency_ms --top 5

if (top > 0 && (sortKey == null || sortKey.isEmpty()))
    throw new IllegalArgumentException("--top requires -s <sortKey>");

try { runNodetool("tablestats", "--top", String.valueOf(top)); }
catch (IllegalArgumentException e) { if (e.getMessage().contains("top K tables")) { /* add sort key and retry */ } else throw e; }

When it happens

Trigger: `nodetool tablestats --top 5` without also passing a valid -s/--sort-key.

Common situations: Users assuming --top works standalone; scripts copied from examples that included -s elsewhere; documentation examples that omitted the sort flag.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• argument for sort must be one of
• argument for top must be a positive integer.
• arguments for -F are json,yaml only.
• arguments for -F are json,yaml only.
• arguments for -F are json,yaml only.

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

Appendix: source

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

    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)