apache/cassandra · error · java.lang.IllegalArgumentException

Unknown table

Error message

Unknown table 

What it means

Nodetool's TableHistograms command validates that every keyspace.table pair the user asked for actually exists in the cluster before querying. It builds the set of all live tables from StorageService and throws IllegalArgumentException when a requested pair is absent. It is a client-side preflight check to avoid querying a nonexistent table.

Solutions

1. Run `nodetool listsnapshots`-style discovery instead: use `nodetool tablehistograms` with no args, or `nodetool cfstats`, to list valid keyspace/table names.
2. Correct the spelling and case of the keyspace and table arguments.
3. Verify you are connected to the intended cluster (check -h/-p port and JMX host).
4. Confirm the table still exists via cqlsh `DESCRIBE TABLES` in the keyspace.

Example fix

// before
nodetool tablehistograms myks MyTable
// after
nodetool tablehistograms myks mytable  // identifiers are stored lowercase unless quoted

String ks = args[0].toLowerCase(); String table = args[1].toLowerCase();
boolean exists = java.util.Optional.ofNullable(StorageService.instance.getLocalHostId()) != null; // then check via listsnapshots/cfstats output
// simplest guard: run `nodetool tablehistograms` with no args first and grep for ks+table

try { runNodetool("tablehistograms", ks, table); }
catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown table")) { /* fall back to listing valid tables */ } else throw e; }

When it happens

Trigger: Running `nodetool tablehistograms <ks> <table>` (or the -a/--keyspace/-t arguments) where the table name is misspelled, the keyspace does not exist, or the table was dropped before the command ran.

Common situations: Typos in table names; case-sensitivity mistakes (Cassandra lowercases unquoted identifiers but the argument is matched literally); running against a different cluster/environment than intended; automation scripts referencing a table removed by a migration.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• argument for top must be a positive integer.
• 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.

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/TableHistograms.java:98

            tablesList.put(ksTbPair.left, ksTbPair.right);
        }
        else if (args.size() == 0)
        {
            // use all tables
            tablesList = allTables;
        }
        else
        {
            throw new IllegalArgumentException("tablehistograms requires <keyspace> <table> or <keyspace.table> format argument.");
        }

        // verify that all tables to list exist
        for (String keyspace : tablesList.keys())
        {
            for (String table : tablesList.get(keyspace))
            {
                if (!allTables.containsEntry(keyspace, table))
                    throw new IllegalArgumentException("Unknown table " + keyspace + '.' + table);
            }
        }

        for (String keyspace : tablesList.keys().elementSet())
        {
            for (String table : tablesList.get(keyspace))
            {
                // calculate percentile of row size and column count
                long[] estimatedPartitionSize = (long[]) probe.getColumnFamilyMetric(keyspace, table, "EstimatedPartitionSizeHistogram");
                long[] estimatedColumnCount = (long[]) probe.getColumnFamilyMetric(keyspace, table, "EstimatedColumnCountHistogram");

                // build arrays to store percentile values
                double[] estimatedRowSizePercentiles = new double[7];
                double[] estimatedColumnCountPercentiles = new double[7];
                double[] offsetPercentiles = new double[]{0.5, 0.75, 0.95, 0.98, 0.99};

                if (ArrayUtils.isEmpty(estimatedPartitionSize) || ArrayUtils.isEmpty(estimatedColumnCount))
                {

View on GitHub (pinned to 88fd0f6a0e)