apache/cassandra · error · ColumnFamilyNotFound

Column family {} not found

Error message

Column family {} not found

What it means

Shell.get_table_meta looks up a table in KeyspaceMetadata.tables. If the table is missing and it is not one of the faked system_auth tables (roles, role_permissions, generated_values), it raises ColumnFamilyNotFound. In cqlsh 'column family' and 'table' are synonyms inherited from the Cassandra/Thrift era.

Source

Thrown at pylib/cqlshlib/cqlshmain.py:566

        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:
            return ksmeta.tables[tablename]

    def get_fake_auth_table_meta(self, ksname, tablename):
        # may be using external auth implementation so internal tables
        # aren't actually defined in schema. In this case, we'll fake
        # them up
        if tablename == 'roles':
            ks_meta = KeyspaceMetadata(ksname, True, None, None)
            table_meta = TableMetadata(ks_meta, 'roles')
            table_meta.columns['role'] = ColumnMetadata(table_meta, 'role', cassandra.cqltypes.UTF8Type)
            table_meta.columns['is_superuser'] = ColumnMetadata(table_meta, 'is_superuser', cassandra.cqltypes.BooleanType)
            table_meta.columns['can_login'] = ColumnMetadata(table_meta, 'can_login', cassandra.cqltypes.BooleanType)
        elif tablename == 'role_permissions':
            ks_meta = KeyspaceMetadata(ksname, True, None, None)
            table_meta = TableMetadata(ks_meta, 'role_permissions')
            table_meta.columns['role'] = ColumnMetadata(table_meta, 'role', cassandra.cqltypes.UTF8Type)
            table_meta.columns['resource'] = ColumnMetadata(table_meta, 'resource', cassandra.cqltypes.UTF8Type)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Verify with DESCRIBE TABLES in the keyspace and correct the table name.
  2. Qualify the table with the right keyspace (ks.tablename).
  3. Refresh schema metadata / reconnect if the table was just created.
  4. Create the missing table with CREATE TABLE if it does not exist.

Example fix

// before
shell.get_table_meta('ks', 'usser')  # ColumnFamilyNotFound
// after
shell.get_table_meta('ks', 'users')  # correct table name
Defensive patterns

Strategy: validation

Validate before calling

ksmeta = shell.get_keyspace_meta(ksname)
if tablename not in ksmeta.tables:
    raise LookupError(f"Table {tablename} missing in {ksname}")

Type guard

def table_exists(shell, ksname, tablename):
    return tablename in shell.get_keyspace_meta(ksname).tables

Try / catch

try:
    tmeta = shell.get_table_meta(ksname, tablename)
except ColumnFamilyNotFound:
    tmeta = None  # fall back to re-describing keyspace

Prevention

When it happens

Trigger: get_table_meta(ksname, tablename) called (directly or via get_column_names, parse_for_select_meta, parse_for_update_meta, perform_simple_statement) with a tablename absent from ksmeta.tables and ksname not being system_auth with a faked table.

Common situations: Typo in a table name in a COPY/DESCRIBE/SELECT path; querying a table that exists in a different keyspace; the table was dropped by another client mid-session; stale driver metadata after CREATE TABLE.

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