apache/cassandra · error · InvalidRequestException

Keyspace '%s' doesn't exist

Error message

Keyspace '%s' doesn't exist

What it means

Thrown while applying CREATE TABLE when metadata.schema.getKeyspaces().getNullable(keyspaceName) returns null. The statement names a keyspace that is not present in the cluster's schema, so the table cannot be created until the keyspace exists (or the name is corrected).

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/CreateTableStatement.java:152

    public String cql()
    {
        if (expandedCql != null)
            return expandedCql;
        return super.cql();
    }

    @Override
    public boolean compatibleWith(ClusterMetadata metadata)
    {
        return metadata.directory.commonSerializationVersion.isAtLeast(Version.V0);
    }

    public Keyspaces apply(ClusterMetadata metadata)
    {
        Keyspaces schema = metadata.schema.getKeyspaces();
        KeyspaceMetadata keyspace = schema.getNullable(keyspaceName);
        if (null == keyspace)
            throw ire("Keyspace '%s' doesn't exist", keyspaceName);

        if (keyspace.hasTable(tableName))
        {
            if (ifNotExists)
                return schema;

            throw new AlreadyExistsException(keyspaceName, tableName);
        }

        // add all user functions to be able to give a good error message to the user if the alter references
        // a function from another keyspace
        UserFunctions.Builder ufBuilder = UserFunctions.builder().add();
        for (KeyspaceMetadata ksm : schema)
            ufBuilder.add(ksm.userFunctions);

        TableMetadata.Builder builder = builder(keyspace.types, ufBuilder.build()).epoch(metadata.nextEpoch());

        // We do not want to set table ID here just yet, since we are using CQL for serialising a fully expanded CREATE TABLE statement.

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Create the keyspace first: CREATE KEYSPACE ks WITH replication = {...};
  2. Fix the keyspace name typo or qualify the table with an existing keyspace: CREATE TABLE existing_ks.t (...).
  3. Run `DESCRIBE KEYSPACES` (or query system_schema.keyspaces) to confirm the keyspace exists.

Example fix

// before
CREATE TABLE myapp.users (id uuid PRIMARY KEY, name text);

// after
CREATE KEYSPACE myapp WITH replication = {'class': 'NetworkTopologyStrategy', 'dc1': 3};
CREATE TABLE myapp.users (id uuid PRIMARY KEY, name text);
Defensive patterns

Strategy: validation

Validate before calling

Row r = session.execute("SELECT keyspace_name FROM system_schema.keyspaces WHERE keyspace_name = ?", ks).one(); if (r == null) throw new IllegalArgumentException("Keyspace does not exist: " + ks);

Type guard

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

Try / catch

try { session.execute(createTableDdl); } catch (InvalidQueryException e) { if (e.getMessage().endsWith("doesn't exist")) { /* run CREATE KEYSPACE first or fix the name */ } else throw e; }

Prevention

When it happens

Trigger: `CREATE TABLE missing_ks.t (...);` or `CREATE TABLE t (...);` while the session's USE keyspace does not exist — schema.getNullable(keyspaceName) returns null in apply().

Common situations: Running table DDL before the keyspace DDL in a migration script; typo in the keyspace name; connecting to a fresh cluster and assuming a default keyspace; migrations applied against the wrong environment.

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/0fbf6e0d30ae2015. Report an issue: GitHub.