apache/cassandra · error · KeyspaceNotFound

Keyspace %r not found.

Error message

Keyspace %r not found.

What it means

Shell.get_keyspace_meta resolves a keyspace name against conn.metadata.keyspaces. If the name is not present in the driver's keyspace metadata, it raises KeyspaceNotFound. Every schema lookup (tables, views, indexes, UDTs, functions) funnels through this method, so it is the root cause for most 'not found' errors in cqlsh.

Source

Thrown at pylib/cqlshlib/cqlshmain.py:549

        return [f.name for f in list(self.get_keyspace_meta(ksname).functions.values())]

    def get_useraggregate_names(self, ksname=None):
        if ksname is None:
            ksname = self.current_keyspace

        return [f.name for f in list(self.get_keyspace_meta(ksname).aggregates.values())]

    def get_cluster_name(self):
        return self.conn.metadata.cluster_name

    def get_partitioner(self):
        return self.conn.metadata.partitioner

    def get_keyspace_meta(self, ksname):
        if ksname in self.conn.metadata.keyspaces:
            return self.conn.metadata.keyspaces[ksname]

        raise KeyspaceNotFound('Keyspace %r not found.' % ksname)

    def get_keyspaces(self):
        return list(self.conn.metadata.keyspaces.values())

    def get_ring(self, ks):
        self.conn.metadata.token_map.rebuild_keyspace(ks, build_if_absent=True)
        return self.conn.metadata.token_map.tokens_to_hosts_by_ks[ks]

    def get_table_meta(self, ksname, tablename):
        if ksname is None:
            ksname = self.current_keyspace
        ksmeta = self.get_keyspace_meta(ksname)
        if tablename not in ksmeta.tables:
            if ksname == 'system_auth' and tablename in ['roles', 'role_permissions', 'generated_values']:
                self.get_fake_auth_table_meta(ksname, tablename)
            else:
                raise ColumnFamilyNotFound("Column family {} not found".format(tablename))
        else:

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Run DESCRIBE KEYSPACES to list existing keyspaces and correct the name.
  2. If the current keyspace was dropped, run USE <valid_keyspace> or clear the session keyspace before further lookups.
  3. Refresh schema metadata (reconnect) if the keyspace was recently created and the driver metadata is stale.
  4. Check cluster schema agreement (nodetool describecluster) if DDL was just applied.

Example fix

// before
shell.get_keyspace_meta('userks')  # KeyspaceNotFound (typo)
// after
shell.get_keyspace_meta('user_ks')  # correct keyspace name
Defensive patterns

Strategy: validation

Validate before calling

if ksname not in shell.conn.metadata.keyspaces:
    raise LookupError(f"Keyspace {ksname!r} not in cluster metadata")

Type guard

def keyspace_exists(shell, ksname):
    return ksname in shell.conn.metadata.keyspaces

Try / catch

try:
    meta = shell.get_keyspace_meta(ksname)
except KeyspaceNotFound:
    meta = None  # prompt user / refresh schema and retry once

Prevention

When it happens

Trigger: Any of get_columnfamily_names/get_materialized_view_names/get_index_names/get_usertype_names/get_usertype_layout/get_userfunction_names called with ksname that is absent from conn.metadata.keyspaces, or with current_keyspace set to a keyspace that no longer exists (e.g. after USE of a dropped keyspace or DROP KEYSPACE elsewhere).

Common situations: Typo in USE <keyspace>; another client dropped the keyspace while this session still points at it; schema disagreement in the cluster; connecting to the wrong cluster/environment (dev vs prod) where the keyspace doesn't exist.

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