apache/cassandra · error · ConfigurationException

Keyspace %s doesn't exist

Error message

Keyspace %s doesn't exist

What it means

CQL3Type.Raw.prepare(keyspace) resolves unqualified UDT references against the given keyspace's metadata. If Schema.instance has no metadata for that keyspace, ConfigurationException('Keyspace <name> doesn't exist') is thrown — the statement references a keyspace that is not defined in the cluster schema.

Source

Thrown at src/java/org/apache/cassandra/cql3/CQL3Type.java:696

        public String keyspace()
        {
            return null;
        }

        public Raw freeze()
        {
            String message = String.format("frozen<> is only allowed on collections, tuples, and user-defined types (got %s)", this);
            throw new InvalidRequestException(message);
        }

        public abstract void validate(ClientState state, String name);

        public CQL3Type prepare(String keyspace)
        {
            KeyspaceMetadata ksm = Schema.instance.getKeyspaceMetadata(keyspace);
            if (ksm == null)
                throw new ConfigurationException(String.format("Keyspace %s doesn't exist", keyspace));
            return prepare(keyspace, ksm.types);
        }

        public abstract CQL3Type prepare(String keyspace, Types udts) throws InvalidRequestException;

        public CQL3Type prepareInternal(String keyspace, Types udts) throws InvalidRequestException
        {
            return prepare(keyspace, udts);
        }

        public boolean referencesUserType(String name)
        {
            return false;
        }

        public static Raw from(CQL3Type type)
        {
            return new RawType(type, false);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Create the keyspace first (CREATE KEYSPACE ...) or correct the spelling of the keyspace name
  2. Check schema consistency: run DESC KEYSPACES / system_schema.keyspace to confirm existence
  3. Ensure migration scripts run in order so the keyspace exists before statements referencing it

Example fix

// before
CREATE TABLE mydata.t (k int PRIMARY KEY, v frozen<mydata.address>); // mydata missing
// after
CREATE KEYSPACE IF NOT EXISTS mydata WITH replication = {'class':'SimpleStrategy','replication_factor':1};
CREATE TABLE mydata.t (k int PRIMARY KEY, v frozen<mydata.address>);
Defensive patterns

Strategy: try-catch

Validate before calling

KeyspaceMetadata ksm = Schema.instance.getKeyspaceMetadata(keyspace);
if (ksm == null) throw new IllegalStateException("Run CREATE KEYSPACE for " + keyspace + " first");

Try / catch

try { session.execute(stmt); } catch (ConfigurationException e) { if (e.getMessage().contains("doesn't exist")) { createKeyspace(keyspace); session.execute(stmt); } }

Prevention

When it happens

Trigger: Preparing a type reference (e.g. a UDT in a CREATE TABLE or INSERT) with a keyspace that was never created, was dropped, or is misspelled; USE-less statements executed against the wrong cluster.

Common situations: Typos in the keyspace name; running DDL scripts out of order (UDT/keyspace creation script not applied yet); environment drift where the keyspace exists in dev but not prod.

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