apache/cassandra · error · IllegalArgumentException

Unknown keyspace

Error message

Unknown keyspace 

What it means

Thrown by StorageService's endpoint-range lookup methods when the caller passes a keyspace name that does not exist in the local schema. Cassandra cannot compute natural replicas (range-to-endpoint mapping) without a replication strategy, which only exists for a registered keyspace, so it fails fast with IllegalArgumentException.

Solutions

1. Verify the keyspace exists: run SELECT keyspace_name FROM system_schema.keyspaces; or cqlsh DESCRIBE KEYSPACES
2. Correct the keyspace name spelling/case passed to the tool or API call
3. Retry after schema agreement is reached (nodetool describecluster / await schema version convergence) if the keyspace was just created
4. Recreate the keyspace if it was accidentally dropped

Example fix

// before
storageService.getRangeToEndpointMap("UserKeyspace");
// after
if (Schema.instance.getKeyspaceMetadata("user_keyspace") != null)
    storageService.getRangeToEndpointMap("user_keyspace");

if (Schema.instance.getKeyspaceMetadata(keyspace) == null)
    throw new IllegalArgumentException("Keyspace does not exist: " + keyspace);
storageService.getRangeToEndpointMap(keyspace);

try { map = ss.getRangeToEndpointMap(ks); } catch (IllegalArgumentException e) { /* unknown keyspace: verify name/schema sync */ }

When it happens

Trigger: Calling describeRing / getRangeToEndpointMap (via JMX nodetool or StorageServiceMBean) with a misspelled or dropped keyspace name; querying before schema is fully distributed to the node; case-sensitive name mismatch ('MyKS' vs 'myks').

Common situations: Typo in nodetool -k flag; running a ring command right after CREATE KEYSPACE on a node that has not yet received the schema change; keyspace dropped by another client between listing and lookup; automation scripts caching stale keyspace names.

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 keyspace
• Keyspace doesn't exist
• Unknown table ' ' in keyspace
• ACCESS TO DATACENTERS operations not supported by…
• ALREADY_EXISTS

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/StorageService.java:2157

                    Token token = TokenMap.nextToken(tokenMap.tokens(), range.right.getToken());
                    rangeToEndpointMap.put(range, metadata.placement(keyspaceMetadata.params.replication)
                                                  .reads.forRange(token).get());
                }
            }
        }
        else
        {
            // Handling the keyspaces which are not handled by CMS like system keyspace which uses LocalStrategy.
            Keyspace ks = Keyspace.openIfExists(keyspace);
            if (ks != null)
            {
                AbstractReplicationStrategy strategy = ks.getReplicationStrategy();
                for (Range<Token> range : ranges)
                    rangeToEndpointMap.put(range, strategy.calculateNaturalReplicas(range.right, metadata));
            }
            else
            {
                throw new IllegalArgumentException("Unknown keyspace " + keyspace);
            }
        }

        return new EndpointsByRange(rangeToEndpointMap);

    }

    public void beforeChange(InetAddressAndPort endpoint, EndpointState currentState, ApplicationState newStateKey, VersionedValue newValue)
    {
        // no-op
    }

    /*
     * Handle the reception of a new particular ApplicationState for a particular endpoint. Note that the value of the
     * ApplicationState has not necessarily "changed" since the last known value, if we already received the same update
     * from somewhere else.
     *
     * onChange only ever sees one ApplicationState piece change at a time (even if many ApplicationState updates were

View on GitHub (pinned to 88fd0f6a0e)