apache/cassandra · error · IllegalArgumentException

Unknown keyspace

Error message

Unknown keyspace '{keyspaceName}'

What it means

partitionKeyToBytes (used by token/sample-key JMX operations like getToken) resolves the keyspace metadata first; if Schema.instance has no such keyspace it throws IllegalArgumentException. The key string must be parsed with the table's partition key type, which requires valid keyspace/table metadata.

Solutions

1. Confirm the keyspace exists via cqlsh DESCRIBE KEYSPACES or system_schema.keyspaces
2. Correct the keyspace name spelling and case
3. Retry after schema agreement if the keyspace was recently created

Example fix

// before
storageService.getToken("Ks", "tbl", "key1");
// after
if (Schema.instance.getKeyspaceMetadata("ks") != null)
    storageService.getToken("ks", "tbl", "key1");

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

try { ss.getToken(ks, table, key); } catch (IllegalArgumentException e) { /* check keyspace name */ }

When it happens

Trigger: Calling StorageServiceMBean.getToken / getSamplePartitionKey paths with a nonexistent or misspelled keyspace name; case mismatch on keyspace identifiers.

Common situations: Typo in scripts driving nodetool gettoken; running the call on a node before schema sync; referencing a keyspace dropped concurrently.

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/3da193b83020c27c. Report an issue: GitHub.

Appendix: source

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

        return Replicas.stringify(replicas, true);
    }

    public EndpointsForToken getNaturalReplicasForToken(String keyspaceName, String cf, String key)
    {
        return getNaturalReplicasForToken(keyspaceName, partitionKeyToBytes(keyspaceName, cf, key));
    }

    public DecoratedKey getKeyFromPartition(String keyspaceName, String table, String partitionKey)
    {
        IPartitioner partitioner = Keyspace.open(keyspaceName).getColumnFamilyStore(table).getPartitioner();
        return partitioner.decorateKey(partitionKeyToBytes(keyspaceName, table, partitionKey));
    }

    private static ByteBuffer partitionKeyToBytes(String keyspaceName, String cf, String key)
    {
        KeyspaceMetadata ksMetaData = Schema.instance.getKeyspaceMetadata(keyspaceName);
        if (ksMetaData == null)
            throw new IllegalArgumentException("Unknown keyspace '" + keyspaceName + "'");

        TableMetadata metadata = ksMetaData.getTableOrViewNullable(cf);
        if (metadata == null)
            throw new IllegalArgumentException("Unknown table '" + cf + "' in keyspace '" + keyspaceName + "'");

        return metadata.partitionKeyType.fromString(key);
    }

    @Override
    public String getToken(String keyspaceName, String table, String key)
    {
        ColumnFamilyStore cfs = Keyspace.open(keyspaceName).getColumnFamilyStore(table);
        return cfs.getPartitioner().getToken(partitionKeyToBytes(keyspaceName, table, key)).toString();
    }

    public EndpointsForToken getNaturalReplicasForToken(String keyspaceName, ByteBuffer key)
    {
        ClusterMetadata metadata = ClusterMetadata.current();

View on GitHub (pinned to 88fd0f6a0e)