apache/cassandra · error · InvalidRequestException

Statement on keyspace %s cannot refer to a user type in keys

Error message

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

What it means

A statement executed in one keyspace referenced a user-defined type qualified with a different keyspace. Cassandra restricts user types to the keyspace where they are defined (CASSANDRA-6643); cross-keyspace type references are rejected.

Source

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

            public RawUT freeze()
            {
                return new RawUT(name, true);
            }

            @Override
            public void validate(ClientState state, String name)
            {
                // nothing to do here
            }

            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)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Recreate the UDT in the statement's keyspace and reference it unqualified
2. Run the statement in the keyspace where the type is defined (USE ks2; or fully qualify the table too)
3. Deduplicate the type definition per keyspace in migration scripts

Example fix

// before (in ks1)
CREATE TABLE ks1.t (id uuid PRIMARY KEY, a ks2.mytype);
// after
// in ks1:
CREATE TYPE ks1.mytype (field text);
CREATE TABLE ks1.t (id uuid PRIMARY KEY, a frozen<mytype>);

// before referencing a UDT, ensure its keyspace equals the statement's keyspace
void checkUdtKeyspace(String statementKeyspace, String udtQualified) {
    int dot = udtQualified.indexOf('.');
    if (dot > 0 && !udtQualified.substring(0, dot).equalsIgnoreCase(statementKeyspace))
        throw new IllegalArgumentException("UDT " + udtQualified + " must live in keyspace " + statementKeyspace);
}

try { session.execute(ddl); } catch (InvalidQueryException e) { if (e.getMessage().contains("cannot refer to a user type in keyspace")) { /* recreate type in target keyspace */ } else throw e; }

When it happens

Trigger: Running `CREATE TABLE ks1.t (x ks2.mytype ...)` or any DDL/DML in ks1 that names a type as `ks2.mytype` where ks2 != the statement's keyspace.

Common situations: Copy-pasting schema DDL between keyspaces; trying to share a UDT across keyspaces; scripts that set one USE keyspace but fully qualify types from another.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Keyspace %s doesn't exist
• Non-frozen UDTs are not allowed inside collections:
• Unknown type
• Invalid field deletion operation for non-UDT column %s
• Unknown keyspace: '" + keyspaceName + "'

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/c7947fffe8cf7f64. Report an issue: GitHub.