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.

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 .
• Commit log flush interval must be positive: %fms
• commitlog_directory must be specified
• Encountered bad header at position
• Encountered bad header at position

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

Appendix: 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)