apache/cassandra · error · InvalidRequestException

Unknown type

Error message

Unknown type

What it means

InvalidRequestException from the RawType prepare path: the type name in a DDL/statement does not resolve to a known type in the statement's keyspace (native types or a declared UDT). The prepare step looks the name up in the Types registry of the keyspace and throws this when the lookup fails; a related guard enforces that user types are only referenced from their own keyspace (#6643).

Source

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

            public CQL3Type prepare(String keyspace, Types udts) throws InvalidRequestException
            {
                if (name.hasKeyspace())
                {
                    // The provided keyspace is the one of the current statement this is part of. If it's different from the keyspace of
                    // the UTName, we reject since we want to limit user types to their own keyspace (see #6643)
                    if (!keyspace.equals(name.getKeyspace()))
                        throw new InvalidRequestException(String.format("Statement on keyspace %s cannot refer to a user type in keyspace %s; "
                                                                        + "user types can only be used in the keyspace they are defined in",
                                                                        keyspace, name.getKeyspace()));
                }
                else
                {
                    name.setKeyspace(keyspace);
                }

                UserType type = udts.getNullable(name.getUserTypeName());
                if (type == null)
                    throw new InvalidRequestException("Unknown type " + name);

                if (frozen)
                    type = type.freeze();
                return new UserDefined(name.toString(), type);
            }

            public boolean referencesUserType(String name)
            {
                return this.name.getStringTypeName().equals(name);
            }

            public boolean supportsFreezing()
            {
                return true;
            }

            public boolean isUDT()
            {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Create the type first: `CREATE TYPE <keyspace>.<name> (...);` then re-run the statement
  2. Check for typos and case sensitivity (unquoted identifiers are lowercased)
  3. Verify you are in/qualifying the correct keyspace (DESCRIBE TYPES / system_schema.types)
  4. If the type was dropped, restore it from schema backups before dependent DDL

Example fix

// before
CREATE TABLE t (id uuid PRIMARY KEY, a mytype); -- mytype missing
// after
CREATE TYPE mytype (field text);
CREATE TABLE t (id uuid PRIMARY KEY, a frozen<mytype>);
Defensive patterns

Strategy: try-catch

Validate before calling

ResultSet rs = session.execute(
    "SELECT keyspace_name, type_name FROM system_schema.types WHERE keyspace_name = ? AND type_name = ?",
    ks, typeName.toLowerCase());
boolean typeExists = rs.iterator().hasNext();

Try / catch

try { session.execute(ddl); } catch (InvalidQueryException e) { if (e.getMessage().startsWith("Unknown type")) { /* run CREATE TYPE first, then retry */ } else throw e; }

Prevention

When it happens

Trigger: Referencing a type name in CREATE TABLE / ALTER TABLE that was never created via CREATE TYPE in the current (or explicitly named) keyspace, or with a typo/case-mismatch, or in the wrong keyspace.

Common situations: Forgetting to run CREATE TYPE before the table DDL; running migrations against a fresh environment; connecting to a cluster where the type lives in another keyspace.

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