What causes "Keyspace '%s' doesn't exist" in apache/cassandra?

Create the keyspace first (CREATE KEYSPACE) or fix its name in the statement

apache/cassandra · error · InvalidRequestException

Keyspace '%s' doesn't exist

Error message

Keyspace '%s' doesn't exist

What it means

Generic existence guard in schema-altering statements: the target keyspace is absent from the current schema when the DDL transformation is applied, so the statement is rejected rather than implicitly creating the keyspace.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/CreateAggregateStatement.java:122

    {
        if (ifNotExists && orReplace)
            throw ire("Cannot use both 'OR REPLACE' and 'IF NOT EXISTS' directives");

        if (!FunctionName.isNameValid(aggregateName))
            throw ire("Aggregate name '%s' is invalid", aggregateName);

        rawArgumentTypes.stream()
                        .filter(raw -> !raw.isImplicitlyFrozen() && raw.isFrozen())
                        .findFirst()
                        .ifPresent(t -> { throw ire("Argument '%s' cannot be frozen; remove frozen<> modifier from '%s'", t, t); });

        if (!rawStateType.isImplicitlyFrozen() && rawStateType.isFrozen())
            throw ire("State type '%s' cannot be frozen; remove frozen<> modifier from '%s'", rawStateType, rawStateType);

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

        /*
         * Resolve the state function
         */

        List<AbstractType<?>> argumentTypes =
            rawArgumentTypes.stream()
                            .map(t -> t.prepare(keyspaceName, keyspace.types).getType().udfType())
                            .collect(toList());
        AbstractType<?> stateType = rawStateType.prepare(keyspaceName, keyspace.types).getType().udfType();
        List<AbstractType<?>> stateFunctionArguments = Lists.newArrayList(concat(singleton(stateType), argumentTypes));

        UserFunction stateFunction =
            keyspace.userFunctions
                    .find(stateFunctionName, stateFunctionArguments)
                    .orElseThrow(() -> ire("State function %s doesn't exist", stateFunctionString()));

        if (stateFunction.isAggregate())

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Create the keyspace first (CREATE KEYSPACE) or fix its name in the statement
Check the case: unquoted identifiers are lowercased; quote 'MyKeyspace' if needed
Verify you are connected to the expected cluster/environment

Example fix

// before
CREATE AGGREGATE kyes.agg(int) ...
// after
CREATE AGGREGATE keys.agg(int) ...  -- or CREATE KEYSPACE kyes WITH replication = ...; first

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

function keyspaceExists(row) { return row != null && typeof row.keyspace_name === 'string'; }

Try / catch

try { session.execute(ddl); }
catch (InvalidRequestException e) { if (e.getMessage().contains("doesn't exist")) ensureKeyspace(extractKs(e)); else throw e; }

Prevention

Verify keyspace existence before running any keyspace-scoped DDL
Keep keyspace names lowercase unless deliberately quoted
Run migrations in environment-aware order (keyspace bootstrap first)

When it happens

Trigger: CREATE AGGREGATE <ks>.<name> (or USE'd keyspace) where ks does not exist in ClusterMetadata.schema at apply time.

Common situations: Typo in keyspace name; running DDL against a cluster/environment where the keyspace was never created or was dropped; case-sensitivity mismatch (unquoted names lowercased).

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

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