apache/cassandra · error · IllegalArgumentException

Unknown keyspace/cf pair (%s.%s)

Error message

Unknown keyspace/cf pair (%s.%s)

What it means

Keyspace.getColumnFamilyStore(String) resolves a column family (table) by name through the schema. If no TableMetadata exists for the (keyspace, cfName) pair, it throws IllegalArgumentException 'Unknown keyspace/cf pair (ks.cf)'. This indicates the caller referenced a table that the schema does not know in this keyspace.

Source

Thrown at src/java/org/apache/cassandra/db/Keyspace.java:205

            }
        }
    }

    public KeyspaceMetadata getMetadata()
    {
        return metadataRef.get();
    }

    public Collection<ColumnFamilyStore> getColumnFamilyStores()
    {
        return Collections.unmodifiableCollection(columnFamilyStores.values());
    }

    public ColumnFamilyStore getColumnFamilyStore(String cfName)
    {
        TableMetadata table = schema.getTableMetadata(getName(), cfName);
        if (table == null)
            throw new IllegalArgumentException(String.format("Unknown keyspace/cf pair (%s.%s)", getName(), cfName));
        return getColumnFamilyStore(table.id);
    }

    public ColumnFamilyStore getColumnFamilyStore(TableId id)
    {
        ColumnFamilyStore cfs = columnFamilyStores.get(id);
        if (cfs == null)
            throw new IllegalArgumentException(String.format("Unknown CF %s %s", id, columnFamilyStores));
        return cfs;
    }

    public ColumnFamilyStore getIfExists(TableId id)
    {
        return columnFamilyStores.get(id);
    }

    public boolean hasColumnFamilyStore(TableId id)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the table exists: `DESCRIBE KEYSPACE <ks>;` or query system_schema.tables — fix the name in your code/config.
2. Create the missing table if it should exist (`CREATE TABLE ...`) before calling operations against it.
3. For loadNewSSTables of orphaned sstables, restore the schema (recreate the exact table) or move the sstable files out of the data directory.
4. Reload the schema (`nodetool reload schema`) and retry if the node has stale schema metadata.

Example fix

// before: unguarded lookup
ColumnFamilyStore cfs = keyspace.getColumnFamilyStore("SensorReadings"); // wrong case
// after: check schema first
if (Schema.instance.getTableMetadata(keyspace.getName(), "sensor_readings") != null)
    cfs = keyspace.getColumnFamilyStore("sensor_readings");

if (Schema.instance.getTableMetadata(keyspace, table) == null)
    throw new IllegalArgumentException("Table " + keyspace + "." + table + " does not exist");

try {
    return keyspace.getColumnFamilyStore(cfName);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown keyspace/cf pair"))
        return null; // or reload schema and retry once
    throw e;
}

When it happens

Trigger: Calling Keyspace.getColumnFamilyStore(name) (directly or via cfs/loadNewSSTables/baseCfs helpers) with a table name that was dropped, renamed, misspelled, or not yet created; also race where a table is dropped between schema lookup and use.

Common situations: Tooling/scripts hard-coding table names with a typo or wrong case; running SSTable loaders (loadNewSSTables) against sstables whose table was dropped; application deployed against an older schema; virtual keyspaces or system tables accessed with wrong names.

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

• The receiver table %s.%s specified by call to function %s ha
• Unknown CF %s %s
• Keyspace " + keyspaceName + " does not exist
• Field '%s' doesn't exist in type '%s.%s'
• Cannot instantiate a non-virtual table

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