apache/cassandra · error · UserTypeNotFound

User type {!r} not found

Error message

User type {!r} not found

What it means

cqlsh's Shell.get_usertype_layout looks up a user-defined type (UDT) by name in the keyspace's driver metadata (ks_meta.user_types). If the name is absent, it raises UserTypeNotFound. This means the requested UDT does not exist in that keyspace's schema as known by the connected cluster.

Source

Thrown at pylib/cqlshlib/cqlshmain.py:523

        layout = self.get_table_meta(ksname, cfname)
        return list(layout.columns)

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

        return list(self.get_keyspace_meta(ksname).user_types)

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

        ks_meta = self.get_keyspace_meta(ksname)

        try:
            user_type = ks_meta.user_types[typename]
        except KeyError:
            raise UserTypeNotFound("User type {!r} not found".format(typename))

        return list(zip(user_type.field_names, user_type.field_types))

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

        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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Verify the UDT exists: run DESCRIBE KEYSPACE <ks> (or check ks_meta.user_types) and correct the type name spelling.
  2. Qualify the UDT with the correct keyspace (types are keyspace-scoped).
  3. Reconnect or refresh schema metadata so the driver picks up newly created types.
  4. Create the missing type with CREATE TYPE if it genuinely does not exist.

Example fix

// before
shell.get_usertype_layout('ks', 'Adress')  # UserTypeNotFound
// after
shell.get_usertype_layout('ks', 'Address')  # match exact UDT name
Defensive patterns

Strategy: try-catch

Validate before calling

ks_meta = shell.get_keyspace_meta(ksname)
if typename not in ks_meta.user_types:
    raise LookupError(f"UDT {typename!r} missing in {ksname}")

Type guard

def has_udt(shell, ksname, typename):
    return typename in shell.get_keyspace_meta(ksname).user_types

Try / catch

try:
    fields = shell.get_usertype_layout(ksname, typename)
except UserTypeNotFound:
    fields = []  # or fall back to re-fetching schema metadata

Prevention

When it happens

Trigger: Calling get_usertype_layout(ksname, typename) where typename is not a key in KeyspaceMetadata.user_types — e.g. a typo'd UDT name, a UDT that exists in a different keyspace, or the driver's schema metadata is stale after a CREATE/DROP TYPE.

Common situations: DESCRIBE TYPE or formatting of query results referencing a UDT after the type was dropped; connecting to a cluster where the type was only created in another keyspace; schema disagreement after a DDL change so the driver hasn't fetched the new type yet.

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