apache/cassandra · error · KeyspaceNotDefinedException

keyspace %s does not exist

Error message

keyspace %s does not exist

What it means

validateTable throws KeyspaceNotDefinedException (a subclass of InvalidRequestException) when the requested keyspace does not exist in the current schema. This happens before any table lookup, so a nonexistent keyspace is reported independently of the table name.

Source

Thrown at src/java/org/apache/cassandra/schema/SchemaProvider.java:102

    {
        assert keyspaceName != null;
        KeyspaceMetadata ksm = distributedKeyspaces().getNullable(keyspaceName);
        return (ksm == null) ? null : ksm.views.getNullable(viewName);
    }

    default Keyspaces getNonLocalStrategyKeyspaces()
    {
        return distributedKeyspaces().filter(keyspace -> keyspace.params.replication.klass != LocalStrategy.class);
    }

    default TableMetadata validateTable(String keyspaceName, String tableName)
    {
        if (tableName.isEmpty())
            throw new InvalidRequestException("non-empty table is required");

        KeyspaceMetadata keyspace = getKeyspaceMetadata(keyspaceName);
        if (keyspace == null)
            throw new KeyspaceNotDefinedException(String.format("keyspace %s does not exist", keyspaceName));

        TableMetadata metadata = keyspace.getTableOrViewNullable(tableName);
        if (metadata == null)
            throw new InvalidRequestException(String.format("table %s does not exist", tableName));

        return metadata;
    }

    default ColumnFamilyStore getColumnFamilyStoreInstance(TableId id)
    {
        TableMetadata metadata = getTableMetadata(id);
        if (metadata == null)
            return null;

        Keyspace instance = getKeyspaceInstance(metadata.keyspace);
        if (instance == null)
            return null;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Create the keyspace (CREATE KEYSPACE ...) or qualify the statement with an existing keyspace.
  2. Check the exact name in system_schema.keyspaces; unquoted names are lowercased.
  3. Add existence checks / IF NOT EXISTS handling in migration scripts before touching tables.

Example fix

// before
session.execute("SELECT * FROM user_events.events WHERE id = 1"); // keyspace user_events missing
// after
session.execute("CREATE KEYSPACE IF NOT EXISTS user_events WITH replication = {'class':'SimpleStrategy','replication_factor':1}");
session.execute("SELECT * FROM user_events.events WHERE id = 1");
Defensive patterns

Strategy: validation

Validate before calling

boolean keyspaceExists(Session s, String ks) {
    return s.execute("SELECT keyspace_name FROM system_schema.keyspaces WHERE keyspace_name = ?", ks.toLowerCase()).one() != null;
}

Try / catch

try { session.execute(query); }
catch (KeyspaceNotDefinedException e) {
    logger.error("Keyspace {} missing — run keyspace bootstrap first", ks);
    throw e;
}

Prevention

When it happens

Trigger: Issuing SELECT/DML/DDL against a keyspace that was never created or was dropped; omitting a keyspace qualifier with no USE keyspace set so an empty/default keyspace name is looked up; typo in the keyspace name.

Common situations: Case-sensitivity mistakes (unquoted identifiers lowercased), keyspace only existing in another cluster/DC, migrations run before keyspace creation, cqlsh sessions without USE.

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/8bb863ced8de9788. Report an issue: GitHub.