apache/cassandra · error · InvalidRequestException

Unknown field ' ' in value of user defined type

Error message

Unknown field '%s' in value of user defined type %s

What it means

Cassandra throws this InvalidRequestException when a user type (UDT) literal in CQL contains a field name that does not exist in the target user type definition. The literal binder (UserTypes.Literal.prepare) checks every field given in the `{field: value, ...}` literal against the UserType's declared field names and rejects unknown ones.

Solutions

1. Correct the field names in the UDT literal to match the type definition (DESCRIBE TYPE / system_schema.types).
2. Verify the keyspace and UDT name in the statement refer to the intended type version.
3. Rebuild prepared statements after altering the UDT so field names are revalidated.
4. Use ALLOW... no — instead generate literals from the actual type metadata rather than hardcoding fields.

Example fix

// before
INSERT INTO ks.t (id, addr) VALUES (1, {street: 'Main', city: 'X'}); // addr has field 'st_address', not 'street'
// after
INSERT INTO ks.t (id, addr) VALUES (1, {st_address: 'Main', city: 'X'});

Set<String> valid = userType.getFieldNames();
for (String f : literalFields) if (!valid.contains(f)) throw new IllegalArgumentException("Unknown UDT field: " + f);

try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().contains("Unknown field")) fixLiteralFields(); else throw e; }

When it happens

Trigger: Executing a statement with a UDT literal like `{street: 'a', city: 'b'}` bound to a UDT column where a field name (e.g. `street`) is not among the type's fields, e.g. after schema drift, a typo, or the literal was parsed before the type was checked.

Common situations: Typos in field names in INSERT/UPDATE literals; UDT definition changed (field renamed/removed) between statement construction and execution; reusing query templates across keyspaces with different UDT definitions.

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

• A TTL must be greater or equal to 0, but was
• A user type cannot contain counters
• A user type cannot contain non-frozen UDTs
• Altering field types is no longer supported
• Argument ' ' cannot be frozen; remove frozen<> modifier from

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/terms/UserTypes.java:168

                Term.Raw raw = entries.get(field);
                if (raw == null)
                    raw = Constants.NULL_LITERAL;
                else
                    ++foundValues;
                Term value = raw.prepare(keyspace, fieldSpecOf(receiver, i));

                if (value instanceof Term.NonTerminal)
                    allTerminal = false;

                values.add(value);
            }
            if (foundValues != entries.size())
            {
                // We had some field that are not part of the type
                for (FieldIdentifier id : entries.keySet())
                {
                    if (!ut.fieldNames().contains(id))
                        throw new InvalidRequestException(String.format("Unknown field '%s' in value of user defined type %s", id, ut.getNameAsString()));
                }
            }

            MultiElements.DelayedValue value = new MultiElements.DelayedValue(((UserType)receiver.type.unwrap()), values);
            return allTerminal ? value.bind(FunctionContext.NONE) : value;
        }

        private void validateAssignableTo(String keyspace, ColumnSpecification receiver) throws InvalidRequestException
        {
            AbstractType<?> unwrapped = receiver.type.unwrap();

            if (!unwrapped.isUDT())
                throw new InvalidRequestException(String.format("Invalid user type literal for %s of type %s", receiver.name, receiver.type.asCQL3Type()));

            UserType ut = (UserType)unwrapped;
            for (int i = 0; i < ut.size(); i++)
            {
                FieldIdentifier field = ut.fieldName(i);

View on GitHub (pinned to 88fd0f6a0e)