apache/cassandra · error · IllegalArgumentException

is not a field defined in this definition

Error message

<name> is not a field defined in this definition

What it means

UserType.getFieldType(name) looks up the field's index in the UDT definition's byName map and throws this IllegalArgumentException when the name is absent. Same family as UDTValue field lookup failures: the driver's in-memory UDT definition does not contain the requested field name.

Solutions

1. List available fields via the UserType definition (getFieldNames) and correct the name.
2. After server-side ALTER TYPE, call cluster.refreshSchemaMetadata() or reconnect to pick up the new field.
3. Normalize the name the same way Metadata.handleId does (case sensitivity rules) before lookup.
4. Regenerate code that hard-codes field names from the current schema.

Example fix

// before
DataType t = userType.getFieldType("Emaill"); // typo
// after
DataType t = userType.getFieldType("email"); // matches definition

if (userType.getFieldNames().stream().noneMatch(f -> f.asInternal().equalsIgnoreCase(name))) throw new IllegalArgumentException("field not in UDT: " + name);

try { return userType.getFieldType(name); } catch (IllegalArgumentException e) { cluster.refreshSchemaMetadata(); return userType.getFieldType(name); } // one retry after refresh

When it happens

Trigger: userType.getFieldType("emaill") (typo), calling before the type definition includes a newly added field (schema refreshed later), passing identifier casing inconsistent with Metadata.handleId normalization.

Common situations: Code-generated accessors generated from an older schema version; rolling schema migrations where nodes/drivers see different definitions; quoted vs unquoted identifier casing differences.

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

• Cannot add new field
• Cannot add new field
• Cannot drop non-frozen column
• Cannot resolve UDTs for keyspace
• Field ' ' doesn't exist in type ' .

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/UserType.java:185

    {
        return Iterators.forArray(byIdx);
    }

    /**
     * Returns the type of a given field.
     *
     * @param name the name of the field. Note that {@code name} obey the usual CQL identifier rules:
     *             it should be quoted if it denotes a case sensitive identifier (you can use {@link
     *             Metadata#quote} for the quoting).
     * @return the type of field {@code name} if this UDT has a field of this name, {@code null}
     * otherwise.
     * @throws IllegalArgumentException if {@code name} is not a field of this UDT definition.
     */
    DataType getFieldType(String name)
    {
        int[] idx = byName.get(Metadata.handleId(name));
        if (idx == null)
            throw new IllegalArgumentException(name + " is not a field defined in this definition");

        return byIdx[idx[0]].getType();
    }

    @Override
    public boolean isFrozen()
    {
        return frozen;
    }

    public UserType copy(boolean newFrozen)
    {
        if (newFrozen == frozen)
        {
            return this;
        }
        else
        {

View on GitHub (pinned to 88fd0f6a0e)