apache/cassandra · error · IllegalArgumentException

Keyspace ${keyspace} not found in cluster metadata.

Error message

Keyspace ${keyspace} not found in cluster metadata.

What it means

Thrown by the placement/describe subcommand of CMSOfflineTool when the requested keyspace does not exist in metadata.schema.getKeyspaces() of the loaded offline cluster metadata. The tool needs the keyspace's replication params to compute DataPlacement, so an unknown keyspace aborts.

Source

Thrown at src/java/org/apache/cassandra/tools/CMSOfflineTool.java:772

     * Prints read and write replica placements for a specific keyspace, sorted by token range.
     * Requires the {@code -ks} option to specify the target keyspace.
     */
    @Command(name = "printdataplacements", description = "Prints data placements in cluster metadata file.")
    static class PrintDataPlacements extends ClusterMetadataToolCmd
    {
        @Option(names = { "-ks", "--keyspace" }, required = true,
        description = "Keyspace to use for printing data placements.")
        private String keyspace;

        @Override
        protected void execute(Output output) throws IOException
        {
            ClusterMetadata metadata = parseClusterMetadata();

            KeyspaceMetadata keyspaceMetadata = metadata.schema.getKeyspaces().getNullable(keyspace);
            if (keyspaceMetadata == null)
            {
                throw new IllegalArgumentException("Keyspace " + keyspace + " not found in cluster metadata.");
            }

            DataPlacement placement = metadata.placement(keyspaceMetadata.params.replication);
            List<Object[]> rows = new ArrayList<>();
            rows.addAll(replicaGroupsToRows(placement.reads, "read"));
            rows.addAll(replicaGroupsToRows(placement.writes, "write"));

            rows.sort((o1, o2) -> {
                Range<Token> left = (Range<Token>) o1[0];
                Range<Token> right = (Range<Token>) o2[0];
                return left.compareTo(right);
            });

            int rangeMaxLength = 0;
            for (Object[] objects : rows)
            {
                rangeMaxLength = Math.max(rangeMaxLength, objects[0].toString().length());
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Verify the exact keyspace name (case-sensitive) against metadata.schema.getKeyspaces().
  2. Regenerate the cluster metadata snapshot after the keyspace was created.
  3. Ensure you are pointing the tool at the intended cluster's metadata file.

Example fix

// before
// cms offline placement --keyspace KeySpace1
// after
// cms offline placement --keyspace keyspace1
Defensive patterns

Strategy: validation

Validate before calling

if (metadata.schema.getKeyspaces().getNullable(keyspace) == null)
    throw new IllegalArgumentException("Keyspace " + keyspace + " not in metadata; known: " + metadata.schema.getKeyspaces().names());

Try / catch

try { tool.describePlacement(keyspace); } catch (IllegalArgumentException e) { logger.error("Keyspace check: " + e.getMessage()); }

Prevention

When it happens

Trigger: Calling the tool with a --keyspace value absent from the schema in the metadata snapshot: misspelled name, keyspace created after the snapshot, or wrong cluster's metadata file.

Common situations: Case-sensitivity mistakes (keyspace names are case-sensitive unless quoted); running against a pre-creation metadata snapshot; typos like 'keyspace1' vs 'ks'.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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