apache/cassandra · error · IllegalArgumentException

Unknown CF %s %s

Error message

Unknown CF %s %s

What it means

Keyspace.getColumnFamilyStore(TableId) looks up the ColumnFamilyStore in this keyspace's in-memory map by TableId. If absent it throws IllegalArgumentException 'Unknown CF <id> <stores>'. Unlike the name-based lookup this uses the live columnFamilyStores registry, so it usually indicates a stale TableId after a drop/recreate or an id from another keyspace.

Source

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

    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)
    {
        return columnFamilyStores.containsKey(id);
    }

    public static void verifyKeyspaceIsValid(String keyspaceName)
    {
        if (null != VirtualKeyspaceRegistry.instance.getKeyspaceNullable(keyspaceName))
            throw new IllegalArgumentException("Cannot perform any operations against virtual keyspace " + keyspaceName);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Re-resolve the store by name instead of a cached id: Schema.instance.getTableMetadata(ks, table) then keyspace.getColumnFamilyStore(TableMetadata.id).
2. Run `nodetool reload schema` and ensure schema agreement on all nodes if drop/recreate races occurred.
3. Restore the table (CREATE TABLE) if operations must target it, or discard the stale work (orphaned sstables/compaction tasks) for the dropped id.
4. Update cached TableIds in tooling after any schema change.

Example fix

// before: cached id may be stale
cfs = keyspace.getColumnFamilyStore(cachedId);
// after: re-resolve by name
table = Schema.instance.getTableMetadata(keyspace.getName(), "my_table");
if (table != null) cfs = keyspace.getColumnFamilyStore(table.id);

TableMetadata tm = Schema.instance.getTableMetadata(ks, table);
if (tm == null) throw new IllegalStateException("table missing");
// use tm.id immediately; do not cache across schema changes

static boolean hasCf(Keyspace ks, TableId id) {
    return ks.getColumnFamilyStores().stream().anyMatch(c -> c.getTableId().equals(id));
}

try {
    return keyspace.getColumnFamilyStore(tableId);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown CF")) {
        Schema.instance.reloadSchema();
        return keyspace.getIfExists(tableId); // null-safe fallback
    }
    throw e;
}

When it happens

Trigger: Passing a TableId obtained from schema metadata/sstables/compaction history that no longer matches a live store (table dropped and recreated gets a new id); id belonging to a different keyspace; race between a DROP TABLE and in-flight operations (compaction, streaming, repair) holding the old id.

Common situations: Restored sstables or compaction logs referencing a pre-drop table id; schema disagreement across nodes after concurrent DROP/CREATE; code caching TableId across deployments; attempts to route reads/writes to a just-dropped table.

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 keyspace/cf pair (%s.%s)
• Can't route consensus request to nonexistent CFS %s.%s
• Got denylist mutation for unknown ks/cf: {}/{}. Skipping ref
• The table '%s' does not exist in the keyspace '%s'.

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