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

Create the keyspace first with CREATE KEYSPACE, or fix the name

apache/cassandra · error · InvalidRequestException

Keyspace '%s' doesn't exist

Error message

Keyspace '%s' doesn't exist

What it means

ALTER KEYSPACE was issued for a keyspace that does not exist in the schema and IF EXISTS was not specified. AlterKeyspaceStatement.apply looks up the keyspace metadata and throws an InvalidRequestException when the lookup returns null and ifExists is false.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/AlterKeyspaceStatement.java:88

        this.ifExists = ifExists;
    }

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

    public Keyspaces apply(ClusterMetadata metadata)
    {
        attrs.validate();

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

        KeyspaceMetadata newKeyspace = keyspace.withSwapped(attrs.asAlteredKeyspaceParams(keyspace.params));

        if (attrs.getReplicationStrategyClass() != null && attrs.getReplicationStrategyClass().equals(SimpleStrategy.class.getSimpleName()))
            Guardrails.simpleStrategyEnabled.ensureEnabled(state);

        if (keyspace.params.replication.isMeta() && !keyspace.name.equals(SchemaConstants.METADATA_KEYSPACE_NAME))
            throw ire("Can not alter a keyspace to use MetaReplicationStrategy");

        if (newKeyspace.params.replication.klass.equals(LocalStrategy.class))
            throw ire("Unable to use given strategy class: LocalStrategy is reserved for internal use.");

        newKeyspace.params.validate(keyspaceName, state, metadata);
        newKeyspace.replicationStrategy.validate(metadata);

        validateNoRangeMovements();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Create the keyspace first with CREATE KEYSPACE, or fix the name
Add IF EXISTS: ALTER KEYSPACE IF EXISTS ks WITH ... to skip when missing
Verify existing keyspaces with DESCRIBE KEYSPACES or system_schema

Example fix

// before
ALTER KEYSPACE myks WITH replication = {'class':'NetworkTopologyStrategy','dc1':3};
// after
CREATE KEYSPACE IF NOT EXISTS myks WITH replication = {'class':'NetworkTopologyStrategy','dc1':3};
ALTER KEYSPACE myks WITH replication = {'class':'NetworkTopologyStrategy','dc1':3};

Defensive patterns

Strategy: validation

Validate before calling

boolean exists = cluster.getMetadata().getKeyspace(keyspace) != null; if (!exists) throw new IllegalStateException("keyspace does not exist: " + keyspace);

Try / catch

try { session.execute(alterCql); } catch (InvalidRequestException e) { if (e.getMessage().contains("doesn't exist")) { session.execute("CREATE KEYSPACE IF NOT EXISTS " + keyspace + " WITH ...", /* then retry alter */); } else throw e; }

Prevention

Run CREATE KEYSPACE IF NOT EXISTS before ALTER in migration scripts
Verify keyspace names against cluster metadata at startup
Use IF EXISTS on ALTER KEYSPACE when absence is acceptable

When it happens

Trigger: `ALTER KEYSPACE ks WITH ...` where ks was never created or was already dropped, without the IF EXISTS clause.

Common situations: Typo in the keyspace name; running migrations against an environment where the keyspace was never created; keyspace dropped by another process between steps.

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