apache/cassandra · error · java.lang.IllegalArgumentException

argument for top must be a positive integer.

Error message

argument for top must be a positive integer.

What it means

TableStats validates that the --top/-t argument is not negative; a negative value throws IllegalArgumentException saying it must be a positive integer. (Note the check is `top < 0`, so zero means 'no limit' and is accepted.)

Solutions

1. Pass a positive integer, or omit --top entirely.
2. Use --top 0 if the tooling requires an explicit 'no limit' value.
3. Sanitize the variable in the calling script before interpolation.

Example fix

// before
nodetool tablestats -s read_latency_ms -t -1
// after
nodetool tablestats -s read_latency_ms -t 10

if (top < 0) throw new IllegalArgumentException("top must be >= 0");

try { runNodetool("tablestats", "-t", String.valueOf(top)); }
catch (IllegalArgumentException e) { if (e.getMessage().contains("top must be a positive")) top = 0; else throw e; }

When it happens

Trigger: `nodetool tablestats -t -3` or scripts interpolating an unvalidated negative variable into the --top flag.

Common situations: Shell scripts computing a limit from upstream data that can be negative; fat-fingered CLI invocations; misuse of 0/-1 as 'unlimited' sentinel where only 0 is valid here.

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

• arguments for -F are json,yaml only.
• Can not parse replication factor
• Keyspace [ ] does not exist.
• Number of commands to display has to be at least 1.
• Parameter --older-than-timestamp has to be a valid instant…

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

Appendix: source

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

        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)