apache/cassandra · error · IllegalArgumentException

Unknown keyspace

Error message

Unknown keyspace 

What it means

CommitLogReplayer.create() validates each keyspace:table pair from the commit log replay filter (cassandra.commitlog_replay_files config or -Dcassandra.commitlog_replay_files). If the named keyspace does not exist in the local schema, IllegalArgumentException("Unknown keyspace X") is thrown before replay begins. Cassandra refuses to replay against a nonexistent keyspace because the replay filter must reference real schema.

Source

Thrown at src/java/org/apache/cassandra/db/commitlog/CommitLogReplayer.java:421

            {
                String trimmedRawPair = rawPair.trim();
                if (trimmedRawPair.isEmpty() || trimmedRawPair.endsWith("."))
                    throw new IllegalArgumentException(format("Invalid pair: '%s'", trimmedRawPair));

                String[] pair = StringUtils.split(trimmedRawPair, '.');

                if (pair.length > 2)
                    throw new IllegalArgumentException(format("%s property contains an item which " +
                                                              "is not in format 'keyspace' or 'keyspace.table' " +
                                                              "but it is '%s'",
                                                              COMMIT_LOG_REPLAY_LIST.getKey(),
                                                              String.join(".", pair)));

                String keyspaceName = pair[0];

                Keyspace ks = Schema.instance.getKeyspaceInstance(keyspaceName);
                if (ks == null)
                    throw new IllegalArgumentException("Unknown keyspace " + keyspaceName);

                if (pair.length == 1)
                {
                    for (ColumnFamilyStore cfs : ks.getColumnFamilyStores())
                        toReplay.put(keyspaceName, cfs.name);
                }
                else
                {
                    ColumnFamilyStore cfs = ks.getColumnFamilyStore(pair[1]);
                    if (cfs == null)
                        throw new IllegalArgumentException(format("Unknown table %s.%s", keyspaceName, pair[1]));

                    toReplay.put(keyspaceName, pair[1]);
                }
            }

            if (toReplay.isEmpty())
                logger.info("All tables will be included in commit log replay.");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Fix the replay filter to use the exact existing keyspace name (run cqlsh 'DESCRIBE KEYSPACES' to confirm).
2. Recreate/restore the keyspace schema before replaying the commit logs.
3. Remove the stale keyspace entry from -Dcassandra.commitlog_replay_files if you only need to skip logs.
4. Check identifier casing: unquoted keyspaces are lowercased in Cassandra.

Example fix

// before
-Dcassandra.commitlog_replay_files=Keyspace1:Standard1
// after (schema has lowercased name)
-Dcassandra.commitlog_replay_files=keyspace1:standard1

if (Schema.instance.getKeyspaceInstance(keyspaceName) == null)
    throw new IllegalArgumentException("Keyspace not found before replay: " + keyspaceName);

try {
    CommitLogReplayer.create(...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown keyspace"))
        logger.error("Fix commitlog_replay filter or restore schema: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Calling CommitLogReplayer.create() with a replay list entry like 'ks1:tbl1' (or 'ks1' alone) where 'ks1' is not present in Schema.instance (getKeyspaceInstance returns null).

Common situations: Typo in the replay filter string; keyspace was dropped or renamed before the replay; replaying commit logs on a node that never had the keyspace; wrong cluster/cassandra.yaml pointing to an empty schema; case-sensitivity confusion (non-quoted identifiers are lowercase).

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 table %s.%s
• Missing required directive CommitLogSync
• Missing value for commitlog_sync_group_window.
• Group sync specified, but commitlog_sync_period found. Only
• Missing value for commitlog_sync_period.

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