apache/cassandra · error · IllegalArgumentException

Unknown table ' ' in keyspace

Error message

Unknown table '{cf}' in keyspace '{keyspaceName}'

What it means

After the keyspace resolves, partitionKeyToBytes looks up the table (or materialized view) via KeyspaceMetadata.getTableOrViewNullable; a null result means the named table/view does not exist in that keyspace, so IllegalArgumentException is thrown with both table and keyspace echoed.

Solutions

  1. List tables with cqlsh DESCRIBE TABLES / DESC <keyspace> and correct the name
  2. Use the exact lowercase identifier unless it was quoted at creation
  3. Check system_schema.tables to confirm the table/view exists on this node

Example fix

// before
storageService.getToken("ks", "UsrTbl", "key1");
// after
storageService.getToken("ks", "usr_tbl", "key1"); // identifier verified in system_schema.tables
Defensive patterns

Strategy: validation

Validate before calling

KeyspaceMetadata ksm = Schema.instance.getKeyspaceMetadata(ks);
if (ksm == null || ksm.getTableOrViewNullable(table) == null)
    throw new IllegalArgumentException("Table/view not found: " + ks + "." + table);

Try / catch

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

Prevention

When it happens

Trigger: Calling getToken/getNaturalEndpoints-style JMX operations with a misspelled table name, a dropped table, or a view name that no longer exists; passing a table name when only a view exists (or vice versa) after renames.

Common situations: Typo in table name; case-sensitive mismatch (unquoted identifiers are lowercase in CQL); table dropped between listing and lookup; scripts referencing pre-migration table 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

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

Appendix: source

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

    {
        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();
        KeyspaceMetadata keyspaceMetadata = Keyspace.open(keyspaceName).getMetadata();
        Token token;
        if (keyspaceMetadata.params.replication.isMeta())
            token = MetaStrategy.partitioner.getToken(key);

View on GitHub (pinned to 88fd0f6a0e)