apache/cassandra · error · java.lang.IllegalArgumentException

Unknown keyspace:

Error message

Unknown keyspace: 

What it means

TableStatsHolder's OptionFilter.verifyKeyspaces validates that every keyspace supplied via nodetool tablestats options actually exists in the cluster. If a user passes a keyspace name that the verifier did not see among live keyspaces, it throws IllegalArgumentException with the offending name. This is a fail-fast input validation for the nodetool CLI.

Solutions

1. Run `nodetool describecluster` or query system_schema.keyspaces to list valid keyspace names and use the exact spelling
2. Re-run the nodetool command with the corrected, case-matched keyspace name
3. Omit the keyspace argument to collect stats for all keyspaces

Example fix

// before
nodetool tablestats MyKeyspace
// after
nodetool tablestats my_keyspace   // exact, case-sensitive name from system_schema.keyspaces

Set<String> existing = session.execute("SELECT keyspace_name FROM system_schema.keyspaces").all().stream().map(r -> r.getString(0)).collect(Collectors.toSet());
if (!existing.contains(ks)) throw new IllegalArgumentException("Unknown keyspace: " + ks);

try { runNodetool(args); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown keyspace:")) { /* prompt for valid keyspace or list system_schema.keyspaces */ } else throw e; }

When it happens

Trigger: Running `nodetool tablestats <ks>` (or tablehistograms/cfstats equivalents) with a keyspace name that does not exist, is misspelled, or differs in case from the actual keyspace.

Common situations: Typo in keyspace name; assuming case-insensitive matching (Cassandra keyspaces are case-sensitive unless quoted); keyspace dropped between listing and stats collection; environment mix-ups (dev vs prod keyspaces).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Unknown tables: " + verifier.get(ks) + " in keyspace: " + ks
• ANY ConsistencyLevel is only supported for writes
• argument for top must be a positive integer.
• arguments for -F are json,yaml only.
• Can not parse replication factor

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/stats/TableStatsHolder.java:643

        }

        public boolean isKeyspaceIncluded(String keyspace)
        {
            // supplying empty params list is treated as wanting to display all keyspaces and tables
            if (filterList.isEmpty())
                return !ignoreMode;

            // Note that if there is any table for the keyspace, we want to include the keyspace irregarding
            // of the ignoreMode, since the ignoreMode then apply to the table inside the keyspace but the
            // keyspace itself is not ignored
            return filter.get(keyspace) != null || ignoreMode;
        }

        public void verifyKeyspaces(Collection<String> keyspaces)
        {
            for (String ks : verifier.keySet())
                if (!keyspaces.contains(ks))
                    throw new IllegalArgumentException("Unknown keyspace: " + ks);
        }

        public void verifyTables()
        {
            for (String ks : filter.keySet())
                if (!verifier.get(ks).isEmpty())
                    throw new IllegalArgumentException("Unknown tables: " + verifier.get(ks) + " in keyspace: " + ks);
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)