apache/cassandra · error · InvalidRequestException

Unknown field %s for column %s

Error message

Unknown field %s for column %s

What it means

Thrown when a CQL UDT field access expression references a field name that does not exist in the User Defined Type of the target column. `ElementExpression.prepare()` looks up the field via `userType.fieldPosition(udtField)`; a return value of -1 means no field with that name is declared, so the expression cannot be prepared.

Source

Thrown at src/java/org/apache/cassandra/cql3/ElementExpression.java:232

        {
            if (kind == Kind.COLLECTION_ELEMENT)
            {
                AbstractType<?> baseType = column.type.unwrap();

                if (!(baseType.isCollection()))
                    throw invalidRequest("Invalid element access syntax for non-collection column %s", column.name);

                Term term = prepareCollectionElement(column);
                CollectionType<?> collectionType = (CollectionType<?>) baseType;
                AbstractType<?> elementType = collectionType.valueComparator();
                AbstractType<?> keyOrIndexType = collectionType.isMap() ? ((MapType<?, ?>) collectionType).getKeysType() : Int32Type.instance;
                return new ElementExpression(kind, elementType, keyOrIndexType, term);
            }

            UserType userType = (UserType) column.type;
            int fieldPosition = userType.fieldPosition(udtField);
            if (fieldPosition == -1)
                throw invalidRequest("Unknown field %s for column %s", udtField, column.name);

            return new ElementExpression(kind,
                                         userType.type(fieldPosition),
                                         UTF8Type.instance,
                                         new Constants.Value(udtField.bytes));
        }

        private Term prepareCollectionElement(ColumnMetadata receiver)
        {
            ColumnSpecification elementSpec;
            switch ((((CollectionType<?>) receiver.type.unwrap()).kind))
            {
                case LIST:
                    elementSpec = Lists.indexSpecOf(receiver);
                    break;
                case MAP:
                    elementSpec = Maps.keySpecOf(receiver);
                    break;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Run `DESCRIBE TYPE <keyspace>.<type>` and confirm the exact field name and its case
2. Fix the field name in the CQL statement to match an existing UDT field
3. If the field should exist, add it with `ALTER TYPE <type> ADD <field> <type>`
4. Re-fetch schema metadata in the driver after UDT changes before re-preparing statements

Example fix

// before
SELECT address.postcode FROM users;  -- UDT has no 'postcode'
// after
SELECT address.zip FROM users;       -- matches ALTER TYPE addr ADD zip text

// Check the UDT field exists before building the query
UserType udt = (UserType) session.getMetadata().getKeyspace(ks).getUserDefinedType(typeName).getType();
if (udt.fieldPosition(fieldName) < 0)
    throw new IllegalArgumentException("UDT " + typeName + " has no field " + fieldName);

boolean hasUdtField(UserType udt, String field) {
    return udt != null && udt.fieldPosition(field) >= 0;
}

When it happens

Trigger: CQL like `SELECT address.zip FROM t` or `WHERE addr['city'] = ...` where `address` is a UDT lacking a `zip`/`city` field; casing mismatches (UDT fields are case-sensitive as stored); querying after the UDT was altered and the field was dropped or renamed.

Common situations: UDT schema drift between environments; application code referencing an old UDT field name after `ALTER TYPE ... RENAME`/`ADD`; misspelled field names; client built statements against a stale schema version.

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

• Invalid element access syntax for non-collection column %s
• Cannot add new field %s of type %s to user type %s as it wou
• REVOKE operation is not supported by AllowAllAuthorizer
• Not enough bytes to read size of %dth field %s
• Not enough bytes to read %dth field %s

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